feat: Initial commit

Author: magifd2

.gemini/GEMINI.md

@@ -0,0 +1,138 @@
+# **Gemini Project Guidelines**
+
+This document outlines the development and build rules specific to this project, intended for the Gemini agent. All development must strictly adhere to these principles to ensure the project's long-term quality, security, and maintainability.
+
+For a detailed history of development and key decisions, please refer to the Development Log.  
+For future development plans and roadmap, please refer to the Development Plan.
+
+## **I. Core Philosophy & Overarching Principles**
+
+*(哲学と最優先事項)*
+
+These are the absolute, non-negotiable principles that guide all other decisions.  
+(これらは他のすべての決定を導く、絶対的で交渉の余地のない原則です。)
+
+### **I-1. Security First Principle (セキュリティ第一原則)**
+
+* Security is the highest priority, overriding all other considerations such as functionality or performance. All code, dependencies, and configurations must be reviewed for potential security vulnerabilities before being committed.  
+* Never trust user input, including environment variables. All external inputs must be validated and sanitized to prevent injection attacks.  
+* Sensitive information (API keys, credentials) must never be hardcoded or stored in insecure locations. Configuration files containing sensitive information must be stored with restrictive permissions (e.g., 0600 for files, 0700 for directories).
+
+### **I-2. Testability First Principle (テスト容易性第一の原則)**
+
+* Prioritize practical "testability" over theoretical "beauty" in design. If a design pattern makes unit testing significantly difficult (e.g., self-registration via init()), it is forbidden.  
+* Always ask, "How will I test this code?" Code that cannot be answered should not be written. Easily testable code is inherently loosely coupled and easy to understand.
+
+## **II. Design & Implementation Principles**
+
+*(設計と実装の原則)*
+
+These principles govern how code should be designed and written.  
+(これらはコードをどのように設計し、書くべきかを規定する原則です。)
+
+### **II-1. Explicit is Better than Implicit (暗黙的な挙動の禁止)**
+
+* Forbid "magical" implementations like changing global state in init() or behavior that changes merely by importing a package.  
+* Dependency Injection must always be done explicitly (e.g., via function arguments). This makes code behavior traceable and easy to mock in tests.
+
+### **II-2. Code Style and Quality (コードのスタイルと品質)**
+
+* Adhere to standard Go formatting (gofmt) and idiomatic Go practices.  
+* Keep functions concise and focused on a single responsibility.  
+* Identify and address the root cause of bugs, avoiding temporary or superficial fixes.
+
+### **II-3. Dependency Management (依存関係の管理)**
+
+* Use Go Modules for dependency management.  
+* Run go mod tidy after adding or removing dependencies to ensure go.mod and go.sum are up-to-date.  
+* Regularly scan project dependencies for known vulnerabilities using make vulncheck.
+
+## **III. Development Process & Workflow**
+
+*(開発プロセスとワークフロー)*
+
+These rules define the mandatory process for all development activities.  
+(これらはすべての開発活動における必須のプロセスを定義するルールです。)
+
+### **III-1. Definition of "Major Refactoring" (「大規模改修」の定義)**
+
+Any change that meets one or more of the following criteria is considered a "Major Refactoring" and requires prior approval of a detailed development plan, including impact analysis and testing strategy.
+
+* **Changes to Initialization Logic**: Any modification involving init() functions, global variables, or package initialization order.  
+* **Changes to Core Interfaces**: Modifying the signature of a central interface like Provider.  
+* **Widespread Impact**: A change that requires modifications across three or more packages.  
+* **Introduction of Cross-Cutting Concerns**: Adding or changing functionality that affects multiple components, such as authentication, logging, or caching.
+
+### **III-2. Safe Refactoring Protocol (安全なリファクタリング規約)**
+
+Even for changes not classified as "Major Refactoring," the following protocol must be strictly followed to prevent system-wide failure.
+
+* **III-2.1.【Establish Baseline】**: Commit the stable, fully-tested state of the code before starting. Commit message: refactor: Start refactoring X.  
+* **III-2.2.【Make Minimal Changes】**: Make the smallest possible incremental change (e.g., extract one function, add one variable).  
+* **III-2.3.【Test Immediately】**: Run make test immediately after the change.  
+  * **On Success**: Commit the change immediately (feat: Introduce Y / refactor: Extract Z). Return to Step **III-2.2**.  
+  * **On Failure**: **Discard all changes immediately (git reset --hard).** Do not attempt to fix the test by modifying other code. A test failure is a critical signal that the **design approach is flawed** and must be re-evaluated from scratch.  
+* **III-2.4.【Complete】**: Achieve the final goal through a series of small, safe, and tested commits.
+
+### **III-3. Commit Message Conventions (コミットメッセージの規約)**
+
+* Use the Conventional Commits specification (e.g., feat:, fix:, refactor:, docs:).  
+* Explain *why* a change was made, not just *what* was changed.
+
+### **III-4. Build and Linting (ビルドとリント)**
+
+* Always use the provided Makefile for building, testing, and cleaning the project.  
+* Ensure all code passes lint checks (make lint) before committing.
+
+## **IV. Tooling & Operational Safety**
+
+*(ツール利用と操作の安全性)*
+
+These rules govern the safe use of development tools and file system operations to prevent irreversible errors.  
+(これらは不可逆的なエラーを防ぐため、開発ツールとファイルシステム操作の安全な利用法を規定するルールです。)
+
+### **IV-1. Safe Code Modification Protocol (安全なコード修正手順)**
+
+* **Problem**: The code replacement tool can be unreliable and may corrupt files.  
+* **Rule**: To prevent file corruption, all code modifications must follow a "diff-and-replace" workflow.  
+* **Process**:  
+  * **IV-1.1.** Generate the complete, modified content of the target file into a **temporary file** (e.g., original_filename.new).  
+  * **IV-1.2.** Execute a diff command between the original file and the new temporary file to verify the changes are exactly as intended.  
+  * **IV-1.3.** Only after visual confirmation of the diff, replace the original file with the temporary file using a mv command.
+
+### **IV-2. Safe File System Operations (安全なファイルシステム操作)**
+
+* **Problem**: Accidental deletion of unintended files due to incorrect path context.  
+* **Rule**: All commands that delete or modify files/directories (e.g., rm, mv) **must use absolute paths.**  
+* **Reason**: This prevents catastrophic errors resulting from operating in an unexpected current working directory. Relative paths are strictly forbidden for destructive operations.
+
+### **IV-3. Safe Git Commit Procedure (安全なGitコミット手順)**
+
+* **Problem**: Complex commit messages can be misinterpreted by the shell, leading to incorrect or failed commits.  
+* **Rule**: To prevent shell interpretation errors, commit messages **must be written to a temporary file first.**  
+* **Process**:  
+  * **IV-3.1.** Write the full commit message (including subject, body, and any special characters) to a temporary file (e.g., .git/COMMIT_MSG).  
+  * **IV-3.2.** Use the git commit -F .git/COMMIT_MSG command to apply the message from the file. Direct command-line commits with -m are forbidden for multi-line or complex messages.
+
+## **V. Documentation Principles**
+
+*(ドキュメンテーションの原則)*
+
+* **V-1. Language Policy**: The primary documentation will be in English (e.g., README.md). Other languages will be provided as auxiliary documentation with a language suffix (e.g., README.ja.md).  
+* **V-2. Maintenance**: When a feature is changed or added, ensure all relevant documentation (README.md, CHANGELOG.md, etc.) is updated accordingly.
+
+## **VI. Agent Operational Protocols (自己規律)**
+
+To prevent critical errors observed during the development of v1.2.0, the following operational protocols are mandatory for all future interactions. These supersede any general instructions where they conflict.
+
+### **VI-1. State-Aware Git Workflow (状態を意識したGitワークフロー)**
+- **Rule:** Before any state-changing Git command (`merge`, `push`, `tag`, `reset`, `branch`), the current state **must** be verified by running `git status && git branch` immediately prior to the operation.
+- **Reason:** To prevent operating on incorrect branches or assumptions about the repository's state.
+
+### **VI-2. Strict Adherence to Safety Protocols (安全プロトコルの厳守)**
+- **Rule:** The "Safe Code Modification Protocol" (IV-1) and "Safe Git Commit Procedure" (IV-3) are not optional guidelines but **mandatory, non-negotiable procedures**. All multi-line commits or complex file modifications **must** use the temporary file and diff method.
+- **Reason:** To eliminate syntax/escaping errors and ensure user verification before changes are applied.
+
+### **VI-3. Rigorous Verification Before Merging (マージ前の厳格な検証)**
+- **Rule:** A feature or fix is not considered "complete" until it has been functionally verified by the user. The standard workflow is: `Implement -> Build -> **Manual Test & User Confirmation** -> Commit -> Merge`. The "Manual Test & User Confirmation" step is mandatory and cannot be skipped.
+- **Reason:** To ensure the implemented code correctly solves the user's problem before it is integrated into the main branch.

.gitignore

@@ -0,0 +1,44 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Code coverage profiles and other test artifacts
+*.out
+coverage.*
+*.coverprofile
+profile.cov
+
+# Dependency directories
+# vendor/
+
+# Go workspace file
+go.work
+go.work.sum
+
+# env file
+.env
+
+# Editor/IDE
+.idea/
+.vscode/
+
+# Build artifacts for scat
+/bin/
+
+# macOS specific files
+.DS_Store
+
+# External files
+.external/**
+
+# Test data
+testdata/
+
+# IDE
+.vscode/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 magifd2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,85 @@
+# ==============================================================================
+# Project Variables
+# ==============================================================================
+
+# The name of the executable
+TARGET := json-to-sqlite
+
+# Get the version from the latest git tag. Fallback to v0.0.0-dev if no tags.
+VERSION ?= $(shell git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0-dev")
+
+# Go build flags
+# -s -w: to make smaller binaries
+# -X main.Version=$(VERSION): to embed the version string
+LDFLAGS := -ldflags="-s -w -X main.Version=$(VERSION)"
+
+# Build output directory
+BUILD_DIR := ./bin
+
+
+# ==============================================================================
+# Main Targets
+# ==============================================================================
+
+.PHONY: all
+all: build
+
+.PHONY: build
+build: build-linux build-windows build-mac
+	@echo "All platforms built successfully."
+
+.PHONY: package
+package: build
+	@echo "Packaging for distribution..."
+	$(MAKE) package-linux
+	$(MAKE) package-windows
+	$(MAKE) package-mac
+	@echo "All packages created in $(BUILD_DIR)"
+
+.PHONY: clean
+clean:
+	@echo "Cleaning up build artifacts..."
+	@rm -rf $(BUILD_DIR)
+
+# ==============================================================================
+# Platform-Specific Build Targets
+# ==============================================================================
+
+.PHONY: build-linux
+build-linux:
+	@echo "Building for Linux (amd64)..."
+	@mkdir -p $(BUILD_DIR)/linux-amd64
+	@GOOS=linux GOARCH=amd64 go build $(LDFLAGS) -o $(BUILD_DIR)/linux-amd64/$(TARGET) .
+
+.PHONY: build-windows
+build-windows:
+	@echo "Building for Windows (amd64)..."
+	@mkdir -p $(BUILD_DIR)/windows-amd64
+	@GOOS=windows GOARCH=amd64 go build $(LDFLAGS) -o $(BUILD_DIR)/windows-amd64/$(TARGET).exe .
+
+# Note: Building a universal binary requires running on macOS with Xcode tools installed.
+.PHONY: build-mac
+build-mac:
+	@echo "Building for macOS (Universal)..."
+	@mkdir -p $(BUILD_DIR)/darwin-universal
+	@GOOS=darwin GOARCH=amd64 go build $(LDFLAGS) -o $(BUILD_DIR)/$(TARGET)-amd64 .
+	@GOOS=darwin GOARCH=arm64 go build $(LDFLAGS) -o $(BUILD_DIR)/$(TARGET)-arm64 .
+	@lipo -create -output $(BUILD_DIR)/darwin-universal/$(TARGET) $(BUILD_DIR)/$(TARGET)-amd64 $(BUILD_DIR)/$(TARGET)-arm64
+	@rm $(BUILD_DIR)/$(TARGET)-amd64 $(BUILD_DIR)/$(TARGET)-arm64
+
+
+# ==============================================================================
+# Packaging Targets
+# ==============================================================================
+
+.PHONY: package-linux
+package-linux:
+	@cd $(BUILD_DIR)/linux-amd64 && tar -czf ../$(TARGET)-$(VERSION)-linux-amd64.tar.gz $(TARGET)
+
+.PHONY: package-windows
+package-windows:
+	@cd $(BUILD_DIR)/windows-amd64 && zip -r ../$(TARGET)-$(VERSION)-windows-amd64.zip $(TARGET).exe
+
+.PHONY: package-mac
+package-mac:
+	@cd $(BUILD_DIR)/darwin-universal && tar -czf ../$(TARGET)-$(VERSION)-darwin-universal.tar.gz $(TARGET)

README.ja.md

@@ -0,0 +1,76 @@
+# json-to-sqlite
+
+JSONデータをインテリジェントに解釈し、SQLiteデータベースに変換する柔軟なコマンドラインツールです。
+
+このツールはテーブルスキーマを自動的に推論し、新しいカラムを追加してスキーマの変更を処理し、ファイルまたは標準入力のどちらからでもJSONを処理できるため、データ処理と永続化のための強力なユーティリティとなります。
+
+## 主な機能
+
+-   **自動スキーマ推論**: JSONオブジェクトの構造からSQLiteのテーブルスキーマをインテリジェントに生成します。
+-   **スキーマの自動更新**: 入力データに新しいフィールドが検出されると、新しいカラムを追加して既存のテーブルをシームレスに更新します。
+-   **柔軟な入力**: ファイルから、または標準入力から直接パイプで渡されたJSONデータを読み取ります。
+-   **データ型マッピング**: JSONの型を適切なSQLiteの型（`TEXT`, `REAL`, `INTEGER`）に自動的にマッピングします。型が競合した場合は安全のために`TEXT`が使用されます。
+-   **ネストされたJSONの処理**: ネストされたJSONオブジェクトや配列を`TEXT`カラムにシリアライズして保存します。
+-   **クロスプラットフォーム**: 付属の`Makefile`により、Windows, Linux, macOS（ユニバーサルバイナリ）向けにビルドできます。
+
+## インストール
+
+### リリースから
+お使いのOSに対応したコンパイル済みのバイナリを[リリースページ](https://github.com/magifd2/json-to-sqlite/releases)からダウンロードしてください。
+
+### ソースからビルド
+ソースからビルドするには、GoとMakeがインストールされている必要があります。
+
+```bash
+# 1. リポジトリをクローン
+git clone https://github.com/magifd2/json-to-sqlite.git
+cd json-to-sqlite
+
+# 2. バイナリをビルド
+make build
+
+# 実行ファイルは ./bin/<OS>-<ARCH>/ に生成されます
+# 例: ./bin/darwin-universal/json-to-sqlite
+```
+
+## 使い方
+
+以下のフラグが使用できます。
+
+-   `-o <パス>`: 出力先のSQLiteデータベースファイルを指定します。(デフォルト: `output.db`)
+-   `-t <テーブル名>`: 作成または更新するテーブル名を指定します。(デフォルト: `data`)
+-   `--version`: ツールのバージョン情報を表示します。
+
+### 使用例
+
+**1. JSONファイルを新しいデータベースに変換する:**
+```bash
+json-to-sqlite -o users.db -t users ./users.json
+```
+
+**2. 他のコマンド（例: `curl`）からJSONデータをパイプで渡す:**
+```bash
+curl "https://api.example.com/data" | json-to-sqlite -o api_data.db -t records
+```
+
+**3. 新しいカラムを持つ可能性のあるデータを既存のデータベースに追加する:**
+```bash
+# new_users.jsonに新しいフィールドがあれば、この2回目のコマンドで'users'テーブルに新しいカラムが追加されます
+json-to-sqlite -o users.db -t users ./new_users.json
+```
+
+## 動作の詳細
+
+### 型のマッピング
+JSONの型は以下のようにSQLiteの型にマッピングされます。
+-   `string` -> `TEXT`
+-   `number` -> `REAL`
+-   `boolean` -> `INTEGER` (`true`は1, `false`は0)
+-   `array` -> `TEXT` (JSON文字列として保存)
+-   `object` -> `TEXT` (JSON文字列として保存)
+
+複数のオブジェクトで同じキーが異なるデータ型を持つ場合、全てのデータを損失なく保存するために、カラムの型は`TEXT`に昇格されます。
+
+## ライセンス
+
+このプロジェクトは [MITライセンス](LICENSE) の下で公開されています。