sqlew 5.1.0 → 5.2.1

package/README.md

@@ -1,190 +1,204 @@
-# sqlew
-
-![sqlew_logo](assets/sqlew-logo.png)
-
-[![npm version](https://img.shields.io/npm/v/sqlew.svg)](https://www.npmjs.com/package/sqlew)
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-
-> **Design decisions, remembered by SQL** — an MCP server for AI agents
-
-## What is sqlew?
-
-### The Problem
-
-Every AI coding session starts from scratch. Your agent doesn't remember that you chose PostgreSQL over MongoDB last week, or that the team agreed on a specific API versioning strategy. Without persistent memory, agents repeat mistakes, contradict earlier decisions, and waste tokens re-discovering context.
-
-### The Solution
-
-sqlew stores your architectural decisions in a structured SQL database. When a new session starts, the AI agent queries past decisions in milliseconds — not by reading through scattered Markdown files, but through efficient SQL lookups with metadata, tags, and similarity detection.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Before sqlew                 │  After sqlew                │
-│───────────────────────────────│─────────────────────────────│
-│  Session 1: "Use PostgreSQL"  │  Session 1: "Use PostgreSQL"│
-│  Session 2: "Use MongoDB?"    │    → decision recorded      │
-│  Session 3: "Use PostgreSQL"  │  Session 2: query → got it  │
-│  (same debate, every time)    │  Session 3: query → got it  │
-│                               │    (instant recall)         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-sqlew is built on the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), so it works with any MCP-compatible AI coding tool.
-
-> _This software does not send any data to external networks. We NEVER collect any data or usage statistics._
-
-## Quick Start
-
-### 1. Install
-
-```bash
-npm install -g sqlew
-```
-
-### 2. Setup
-
-Choose the setup that matches your environment:
-
-#### Claude Code (Plugin)
-
-```bash
-claude plugin marketplace add sqlew-io/sqlew-plugin
-claude plugin install sqlew
-```
-
-The plugin automatically configures MCP server, Skills (Plan Mode guidance), and Hooks (automatic decision capture).
-
-#### Codex CLI
-
-See [sqlew-codex](https://github.com/sqlew-io/sqlew-codex) for Codex CLI integration.
-
-#### Manual
-
-Add to `.mcp.json` in your project root:
-
-```json
-{
-    "mcpServers": {
-        "sqlew": {
-            "command": "sqlew"
-        }
-    }
-}
-```
-
-The database (`~/.config/sqlew/sqlew-shared.db`) and config are auto-created on first run. See [Shared Database](docs/SHARED_DATABASE.md) for details.
-
-### 3. Just use Plan Mode!
-
-That's it. Every time you create a plan and get user approval, your architectural decisions are **automatically recorded**.
-
-No special commands needed — just plan your work normally, and sqlew captures the decisions in the background.
-
-## Features
-
-- **Structured Records** — Decisions stored as relational data with metadata, tags, layers, and version history
-- **Fast Queries** — 2-50ms retrieval via SQL, even with thousands of decisions
-- **Duplicate Detection** — Three-tier similarity scoring (0-100) prevents redundant decisions
-- **Constraint Tracking** — Architectural rules and principles as first-class entities
-- **Auto-Capture** — Hooks automatically record decisions from Plan Mode (Claude Code plugin)
-- **Multi-Database** — SQLite (default), PostgreSQL, MySQL/MariaDB, or Cloud
-- **Git Worktree Ready** — Each worktree shares the same context database
-
-## For Teams (sqlew.io)
-
-Connect to [sqlew.io](https://sqlew.io) for team-shared decisions:
-
-**Step 1: Get your API key**
-
-Visit [sqlew.io](https://sqlew.io) and save your API key:
-
-```bash
-# ~/.config/sqlew/.sqlew.env (shared across all projects)
-SQLEW_API_KEY=your-api-key
-```
-
-**Step 2: Configure each project**
-
-```toml
-# .sqlew/config.toml
-[database]
-type = "cloud"
-
-[project]
-name = "your-project-name"
-```
-
-**Benefits:**
-- All team members share the same decision database
-- Works seamlessly with Git worktree workflows
-- No local database setup required
-
-## Performance
-
-| Metric | Value |
-|--------|-------|
-| Query speed | 2-50ms |
-| Concurrent agents | 5+ simultaneous |
-| Storage efficiency | ~140 bytes/decision |
-| Token savings | 60-75% vs Markdown ADRs |
-
-## Use Cases
-
-- **Architecture Evolution** — Document major decisions with full context and alternatives considered
-- **Pattern Standardization** — Establish coding patterns as constraints, enforce via AI code generation
-- **Cross-Session Continuity** — AI maintains context across days/weeks without re-reading docs
-- **Multi-Agent Coordination** — Multiple AI agents share architectural understanding
-- **Onboarding Acceleration** — New AI sessions instantly understand project history
-
-## Documentation
-
-| Guide | Description |
-|-------|-------------|
-| [ADR Concepts](docs/ADR_CONCEPTS.md) | Architecture Decision Records explained |
-| [Configuration](docs/CONFIGURATION.md) | Config file setup, database options |
-| [Hooks Guide](docs/HOOKS_GUIDE.md) | Claude Code Hooks integration |
-| [Cross Database](docs/CROSS_DATABASE.md) | Multi-database support |
-| [CLI Usage](docs/CLI_USAGE.md) | Database migration, export/import |
-
-### Upgrade Guides
-
-- [Migrating to SaaS](docs/MIGRATION_TO_SAAS.md) — Export local data to sqlew.io cloud
-
-
-### MCP Tools
-
-7 action-based tools: `decision`, `constraint`, `suggest`, `help`, `example`, `use_case`, `queue`
-
-All tools support `action: "help"` for documentation.
-
-## Support
-
-Support development via [GitHub Sponsors](https://github.com/sponsors/sqlew-io).
-
-## Version
-
-Current version: **5.0.8**
-
-See [CHANGELOG.md](CHANGELOG.md) for release history.
-
-**What's New in v5.0.8:**
-
-- **PR ADR enforcement** — PreToolUse Hook blocks `gh pr create` without ADR markers, file-grouped format
-- **Codex CLI support** — Works beyond Claude Code via [sqlew-codex](https://github.com/sqlew-io/sqlew-codex)
-- **Plugin-first architecture** — Simplified setup via sqlew-plugin
-- **Cloud backend** — Connect to [sqlew.io](https://sqlew.io) for team-shared decisions
-
-## License
-
-Apache License 2.0 — Free for commercial and personal use. See [LICENSE](LICENSE) for details.
-
-## Links
-
-- [npm package](https://www.npmjs.com/package/sqlew)
-- [GitHub](https://github.com/sqlew-io/sqlew)
-- [Issues](https://github.com/sqlew-io/sqlew/issues)
-- [Model Context Protocol](https://modelcontextprotocol.io/)
-
----
-
-Built with [MCP SDK](https://github.com/modelcontextprotocol/sdk), [better-sqlite3](https://github.com/WiseLibs/better-sqlite3), and TypeScript.
+# sqlew
+
+![sqlew_logo](assets/sqlew-logo.png)
+
+[![npm version](https://img.shields.io/npm/v/sqlew.svg)](https://www.npmjs.com/package/sqlew)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+> **Design decisions, remembered by SQL** — an MCP server for AI agents
+
+## What is sqlew?
+
+### The Problem
+
+Every AI coding session starts from scratch. Your agent doesn't remember that you chose PostgreSQL over MongoDB last week, or that the team agreed on a specific API versioning strategy. Without persistent memory, agents repeat mistakes, contradict earlier decisions, and waste tokens re-discovering context.
+
+### The Solution
+
+sqlew stores your architectural decisions in a structured SQL database. When a new session starts, the AI agent queries past decisions in milliseconds — not by reading through scattered Markdown files, but through efficient SQL lookups with metadata, tags, and similarity detection.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Before sqlew                 │  After sqlew                │
+│───────────────────────────────│─────────────────────────────│
+│  Session 1: "Use PostgreSQL"  │  Session 1: "Use PostgreSQL"│
+│  Session 2: "Use MongoDB?"    │    → decision recorded      │
+│  Session 3: "Use PostgreSQL"  │  Session 2: query → got it  │
+│  (same debate, every time)    │  Session 3: query → got it  │
+│                               │    (instant recall)         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+sqlew is built on the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), so it works with any MCP-compatible AI coding tool.
+
+> _This software does not send any data to external networks. We NEVER collect any data or usage statistics._
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g sqlew
+```
+
+### 2. Setup
+
+Choose the setup that matches your environment:
+
+#### Claude Code (Plugin)
+
+```bash
+claude plugin marketplace add sqlew-io/sqlew-plugin
+claude plugin install sqlew
+```
+
+The plugin automatically configures MCP server, Skills (Plan Mode guidance), and Hooks (automatic decision capture).
+
+#### Codex CLI (Plugin)
+
+```bash
+codex plugin marketplace add sqlew-io/sqlew-plugin
+codex plugin install sqlew --source sqlew-plugin
+```
+
+After install, open `/hooks` in Codex and trust the bundled sqlew hooks. Enable Plan Mode with `collaboration_modes = true` under `[features]` in your Codex config. The plugin configures MCP server, Skills (plan mode guidance), and Hooks (plan enforcement, PR ADR guard, decision extraction). See [Hooks Guide](docs/HOOKS_GUIDE.md) for caveats (do not duplicate skills in `~/.codex/skills/` or add `[mcp_servers.sqlew]` to `config.toml`).
+
+#### Grok Build (Plugin)
+
+```bash
+npm install -g sqlew
+grok plugin install sqlew-io/sqlew-plugin --trust
+grok plugin update
+```
+
+The plugin configures MCP server, Skills (plan mode guidance), and Hooks (automatic decision capture on `exit_plan_mode`). See [Hooks Guide](docs/HOOKS_GUIDE.md) for setup details and caveats (do not duplicate hooks in `~/.grok/hooks/` or `config.toml`).
+
+#### Manual
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+    "mcpServers": {
+        "sqlew": {
+            "command": "sqlew"
+        }
+    }
+}
+```
+
+The database (`~/.config/sqlew/sqlew-shared.db`) and config are auto-created on first run. See [Shared Database](docs/SHARED_DATABASE.md) for details.
+
+### 3. Just use Plan Mode!
+
+That's it. Every time you create a plan and get user approval, your architectural decisions are **automatically recorded**.
+
+No special commands needed — just plan your work normally, and sqlew captures the decisions in the background.
+
+## Features
+
+- **Structured Records** — Decisions stored as relational data with metadata, tags, layers, and version history
+- **Fast Queries** — 2-50ms retrieval via SQL, even with thousands of decisions
+- **Duplicate Detection** — Three-tier similarity scoring (0-100) prevents redundant decisions
+- **Constraint Tracking** — Architectural rules and principles as first-class entities
+- **Auto-Capture** — Hooks automatically record decisions from Plan Mode (Claude Code, Codex, and Grok Build via sqlew-plugin)
+- **Multi-Database** — SQLite (default), PostgreSQL, MySQL/MariaDB, or Cloud
+- **Git Worktree Ready** — Each worktree shares the same context database
+
+## For Teams (sqlew.io)
+
+Connect to [sqlew.io](https://sqlew.io) for team-shared decisions:
+
+**Step 1: Get your API key**
+
+Visit [sqlew.io](https://sqlew.io) and save your API key:
+
+```bash
+# ~/.config/sqlew/.sqlew.env (shared across all projects)
+SQLEW_API_KEY=your-api-key
+```
+
+**Step 2: Configure each project**
+
+```toml
+# .sqlew/config.toml
+[database]
+type = "cloud"
+
+[project]
+name = "your-project-name"
+```
+
+**Benefits:**
+- All team members share the same decision database
+- Works seamlessly with Git worktree workflows
+- No local database setup required
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Query speed | 2-50ms |
+| Concurrent agents | 5+ simultaneous |
+| Storage efficiency | ~140 bytes/decision |
+| Token savings | 60-75% vs Markdown ADRs |
+
+## Use Cases
+
+- **Architecture Evolution** — Document major decisions with full context and alternatives considered
+- **Pattern Standardization** — Establish coding patterns as constraints, enforce via AI code generation
+- **Cross-Session Continuity** — AI maintains context across days/weeks without re-reading docs
+- **Multi-Agent Coordination** — Multiple AI agents share architectural understanding
+- **Onboarding Acceleration** — New AI sessions instantly understand project history
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [ADR Concepts](docs/ADR_CONCEPTS.md) | Architecture Decision Records explained |
+| [Configuration](docs/CONFIGURATION.md) | Config file setup, database options |
+| [Hooks Guide](docs/HOOKS_GUIDE.md) | Claude Code, Codex, and Grok Build integration |
+| [Cross Database](docs/CROSS_DATABASE.md) | Multi-database support |
+| [CLI Usage](docs/CLI_USAGE.md) | Database migration, export/import |
+
+### Upgrade Guides
+
+- [Migrating to SaaS](docs/MIGRATION_TO_SAAS.md) — Export local data to sqlew.io cloud
+
+
+### MCP Tools
+
+7 action-based tools: `decision`, `constraint`, `suggest`, `help`, `example`, `use_case`, `queue`
+
+All tools support `action: "help"` for documentation.
+
+## Support
+
+Support development via [GitHub Sponsors](https://github.com/sponsors/sqlew-io).
+
+## Version
+
+Current version: **5.2.0**
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+**What's New in v5.2.0:**
+
+- **Grok Build support** — Plan-to-ADR via [sqlew-plugin](https://github.com/sqlew-io/sqlew-plugin) (`grok plugin install sqlew-io/sqlew-plugin --trust`)
+- **Grok plan.md injection** — Decision/Constraint template appended on `enter_plan_mode`
+- **Hook normalization** — Single CLI hook handlers work under both Claude Code and Grok Build
+
+## License
+
+Apache License 2.0 — Free for commercial and personal use. See [LICENSE](LICENSE) for details.
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/sqlew)
+- [GitHub](https://github.com/sqlew-io/sqlew)
+- [Issues](https://github.com/sqlew-io/sqlew/issues)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+
+---
+
+Built with [MCP SDK](https://github.com/modelcontextprotocol/sdk), [better-sqlite3](https://github.com/WiseLibs/better-sqlite3), and TypeScript.

package/dist/adapters/mysql-adapter.js

@@ -130,9 +130,9 @@ export class MySQLAdapter extends BaseAdapter {
     async tableExists(tableName) {
         const knex = this.getKnex();
         const database = this.config.connection.database;
-        const result = await knex.raw(`SELECT TABLE_NAME
-       FROM INFORMATION_SCHEMA.TABLES
-       WHERE TABLE_SCHEMA = ?
+        const result = await knex.raw(`SELECT TABLE_NAME
+       FROM INFORMATION_SCHEMA.TABLES
+       WHERE TABLE_SCHEMA = ?
          AND TABLE_NAME = ?`, [database, tableName]);
         return result[0].length > 0;
     }

package/dist/adapters/postgresql-adapter.js

@@ -130,9 +130,9 @@ export class PostgreSQLAdapter extends BaseAdapter {
     async tableExists(tableName) {
         const knex = this.getKnex();
         const database = this.config.connection.database;
-        const result = await knex.raw(`SELECT table_name
-       FROM information_schema.tables
-       WHERE table_catalog = ?
+        const result = await knex.raw(`SELECT table_name
+       FROM information_schema.tables
+       WHERE table_catalog = ?
          AND table_name = ?`, [database, tableName]);
         return result.rows.length > 0;
     }

package/dist/cli/db-export.js

@@ -13,38 +13,38 @@ import { getDefaultDbPath } from '../config/global-config.js';
  * Show help message for db:export command
  */
 export function showDbExportHelp() {
-    console.log(`
-sqlew db:export - Export project data to JSON format
-
-USAGE:
-  npm run db:export -- [output-file] [key=value ...]
-
-ARGUMENTS:
-  [output-file]            Output file (optional, default: stdout)
-
-OPTIONS (use key=value format):
-  project=<name>           Export specific project (default: auto-detect from config.toml)
-  project=all              Export all projects (explicit opt-in required)
-  db-path=<path>           SQLite database path
-  config=<path>            Config file path
-
-EXAMPLES:
-  # Export current project (auto-detect from .sqlew/config.toml)
-  npm run db:export -- data.json
-
-  # Export specific project
-  npm run db:export -- data.json project=myproject
-
-  # Export all projects (explicit)
-  npm run db:export -- backup.json project=all
-
-  # Export to stdout
-  npm run db:export -- project=myproject
-
-WORKFLOW:
-  1. Export: npm run db:export -- data.json project=myproject
-  2. Copy JSON to target
-  3. Import: npm run db:import -- data.json
+    console.log(`
+sqlew db:export - Export project data to JSON format
+
+USAGE:
+  npm run db:export -- [output-file] [key=value ...]
+
+ARGUMENTS:
+  [output-file]            Output file (optional, default: stdout)
+
+OPTIONS (use key=value format):
+  project=<name>           Export specific project (default: auto-detect from config.toml)
+  project=all              Export all projects (explicit opt-in required)
+  db-path=<path>           SQLite database path
+  config=<path>            Config file path
+
+EXAMPLES:
+  # Export current project (auto-detect from .sqlew/config.toml)
+  npm run db:export -- data.json
+
+  # Export specific project
+  npm run db:export -- data.json project=myproject
+
+  # Export all projects (explicit)
+  npm run db:export -- backup.json project=all
+
+  # Export to stdout
+  npm run db:export -- project=myproject
+
+WORKFLOW:
+  1. Export: npm run db:export -- data.json project=myproject
+  2. Copy JSON to target
+  3. Import: npm run db:import -- data.json
 `);
 }
 /**

package/dist/cli/db-import.js

@@ -13,36 +13,36 @@ import { getDefaultDbPath } from '../config/global-config.js';
  * Show help message for db:import command
  */
 export function showDbImportHelp() {
-    console.log(`
-sqlew db:import - Import project data from JSON export
-
-USAGE:
-  npm run db:import -- <source-file> [key=value ...]
-
-ARGUMENTS:
-  <source-file>            JSON export file (required)
-
-OPTIONS (use key=value format):
-  project-name=<name>      Target project name (default: from JSON)
-  skip-if-exists=true      Skip if project exists (default: true)
-  dry-run=true             Validate only, don't import
-  db-path=<path>           SQLite database path
-  config=<path>            Config file path
-
-EXAMPLES:
-  # Import from JSON
-  npm run db:import -- data.json
-
-  # Import with custom project name
-  npm run db:import -- data.json project-name=newproject
-
-  # Dry run validation
-  npm run db:import -- data.json dry-run=true
-
-WORKFLOW:
-  1. Export: npm run db:export -- data.json project=myproject
-  2. Copy JSON to target
-  3. Import: npm run db:import -- data.json
+    console.log(`
+sqlew db:import - Import project data from JSON export
+
+USAGE:
+  npm run db:import -- <source-file> [key=value ...]
+
+ARGUMENTS:
+  <source-file>            JSON export file (required)
+
+OPTIONS (use key=value format):
+  project-name=<name>      Target project name (default: from JSON)
+  skip-if-exists=true      Skip if project exists (default: true)
+  dry-run=true             Validate only, don't import
+  db-path=<path>           SQLite database path
+  config=<path>            Config file path
+
+EXAMPLES:
+  # Import from JSON
+  npm run db:import -- data.json
+
+  # Import with custom project name
+  npm run db:import -- data.json project-name=newproject
+
+  # Dry run validation
+  npm run db:import -- data.json dry-run=true
+
+WORKFLOW:
+  1. Export: npm run db:export -- data.json project=myproject
+  2. Copy JSON to target
+  3. Import: npm run db:import -- data.json
 `);
 }
 /**

package/dist/cli/hooks/codex-transcript.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Codex transcript helpers for Plan-to-ADR extraction.
+ *
+ * Codex stores session rollouts as JSONL under ~/.codex/sessions/ rather than
+ * a dedicated plan.md file. These helpers locate the transcript and extract
+ * assistant plan text written during collaboration Plan mode.
+ *
+ * @since v5.2.1
+ */
+/**
+ * Recursively search ~/.codex/sessions for a rollout JSONL ending with sessionId.
+ */
+export declare function findCodexTranscriptPath(sessionId: string): string | null;
+/**
+ * Extract assistant plan text from a Codex rollout JSONL transcript.
+ * Returns concatenated assistant output from turns that ran in Plan mode.
+ */
+export declare function extractPlanMarkdownFromCodexTranscript(transcriptPath: string): string | null;
+/**
+ * Write extracted Codex plan text to a project-local temp markdown file.
+ */
+export declare function materializeCodexPlanFile(projectPath: string, sessionId: string, content: string): string;
+//# sourceMappingURL=codex-transcript.d.ts.map

package/dist/cli/hooks/codex-transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-transcript.d.ts","sourceRoot":"","sources":["../../../src/cli/hooks/codex-transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYxE;AAoCD;;;GAGG;AACH,wBAAgB,sCAAsC,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoE5F;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxG"}