Initial dataxl CLI

docs/architecture.md

@@ -0,0 +1,93 @@
+# Architecture
+
+`dataxl` は、ファイル形式ごとの差を小さくするために、内部表現を2つに分けています。
+
+- structured value: JSON/YAML/TOMLから読める `map[string]any`, `[]any`, scalar
+- table: Excel/CSV/TSVに近い `Header []string` と `Rows [][]string`
+
+変換は原則として次のどれかです。
+
+- structured -> structured
+- structured -> table
+- table -> structured
+- table -> table
+
+## Format Adapters
+
+各形式の処理は `cmd/dataxl/main.go` の以下の関数に集約しています。
+
+- `parseStructured`
+- `encodeStructured`
+- `parseTable`
+- `encodeTable`
+
+現在はCLIが小さいため単一ファイルに置いています。形式やオプションが増えたら、
+`internal/format` や `internal/table` へ分割する余地があります。
+
+## Table Model
+
+表形式は必ず1行目をヘッダーとして扱います。
+
+```go
+type table struct {
+    Header []string
+    Rows   [][]string
+}
+```
+
+CSV/TSV/XLSXの読み込みでは、短い行を空文字で埋めて列数を揃えます。
+XLSXの書き出しではヘッダーを太字にし、1行目を固定します。
+
+## Flattening
+
+structured -> table では、入れ子のmap/arrayを列パスへ展開します。
+
+- map: `user.name`
+- array: `items[0].sku`
+- top-level scalar: `value`
+
+列順は安定性を優先してソートしています。Excel上で列の位置が変わっても、
+ヘッダー名を見て復元するため、列順には依存しません。
+
+## Unflattening
+
+table -> structured では、ヘッダーのパス表現からmap/arrayを復元します。
+
+例:
+
+```text
+items[0].sku
+```
+
+は次の構造になります。
+
+```json
+{
+  "items": [
+    {
+      "sku": "..."
+    }
+  ]
+}
+```
+
+セル値は `parseCell` で軽く型推定します。
+
+- 空文字: `""`
+- `true` / `false`: boolean
+- 整数: int64
+- 小数または指数表記: float64
+- その他: string
+
+## TOML Output
+
+TOMLはトップレベル配列を直接表せないため、表からTOMLへ出力する場合など、
+トップレベルがmapでない値は `rows` キーに包んで出力します。
+
+## Dependencies
+
+- `github.com/xuri/excelize/v2`: XLSX読み書き
+- `gopkg.in/yaml.v3`: YAML読み書き
+- `github.com/BurntSushi/toml`: TOML読み書き
+
+Go 1.24以上を前提にしています。

docs/development.md

@@ -0,0 +1,74 @@
+# Development
+
+## Requirements
+
+- Go 1.24 or later
+
+## Setup
+
+```sh
+git clone https://git.rumginger.org/agent/dataxl.git
+cd dataxl
+go mod download
+```
+
+## Common Commands
+
+Format code:
+
+```sh
+gofmt -w cmd/dataxl/*.go
+```
+
+Run tests:
+
+```sh
+go test ./...
+```
+
+Build:
+
+```sh
+go build ./cmd/dataxl
+```
+
+Run locally:
+
+```sh
+go run ./cmd/dataxl -from yaml -to tsv -i examples/people.yaml
+```
+
+## Test Coverage
+
+The current tests cover:
+
+- YAML -> TSV flattening
+- TSV -> JSON path restoration
+- JSON -> XLSX -> JSON round trip
+
+When adding a new format or path rule, add tests around both directions where
+possible.
+
+## Release Notes
+
+There is no automated release pipeline yet. A minimal release flow is:
+
+```sh
+go test ./...
+git tag v0.1.0
+git push origin main --tags
+```
+
+After tags exist, users can install a specific version:
+
+```sh
+go install git.rumginger.org/agent/dataxl/cmd/dataxl@v0.1.0
+```
+
+## Design Guidelines
+
+- Keep stdin/stdout usable for shell pipelines.
+- Keep TSV behavior predictable because it is the main Excel clipboard format.
+- Preserve headers as the contract between spreadsheet data and structured data.
+- Prefer explicit errors over silent best-effort conversion when a format is unsupported.
+- Keep dependencies small unless a format needs a mature parser/writer.