hikoutei 0.5.21 → 0.5.22

package/README.ja.md

@@ -121,9 +121,12 @@ API クライアントを直接使ってください。
 
 Google Sheets の同期はサービス側の関心事です。アプリケーションは provider
 クライアントを import したり、`createTypedSheets()` にシートルートを渡したり、
-書き込みごとに操作を選んだりしません。同期ランタイムはサービスアカウントを
-使う単一の Google Sheets API provider(内部 `googleSheetsApi` bootstrap オプ
-ション)を使用します — Apps Script のデプロイは不要です。
+書き込みごとに操作を選んだりしません — ルート API が受け取るのは `dbName` と
+`entities` だけです。同期ランタイムはサービスアカウントを使う単一の内部
+Google Sheets API provider を使用します — Apps Script のデプロイは不要です。
+同期の自動開始は `HIKOUTEI_SYNC_SPREADSHEET_URL` と
+`GOOGLE_APPLICATION_CREDENTIALS` で選択され、設定する公開
+`googleSheetsApi` bootstrap オプションはありません。
 
 ### 環境変数による同期の自動開始
 
@@ -145,7 +148,7 @@ const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities
 不正、資格情報ファイルの欠落・不正、スプレッドシートに共有されていない
 サービスアカウント (共有すべきメールアドレスをエラーが教えてくれます)。
 
-### Service-account provider (googleSheetsApi)
+### 手動でのサービスアカウント設定
 
 1. **サービスアカウントを作成する。** Cloud プロジェクトで Google Sheets API
    を有効化し、`https://www.googleapis.com/auth/spreadsheets` スコープの
@@ -157,9 +160,17 @@ const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities
    `GOOGLE_APPLICATION_CREDENTIALS` に、スプレッドシート ID は追跡されない
    シークレットストアに置きます。キーをブラウザコードや Git に入れないで
    ください。
-3. **内部 sync bootstrap を起動する。** `googleSheetsApi` を設定すると、
-   登録済みタブのヘッダーを作成・検証した後、outbox 配信と User_Input ポー
-   リングを開始します。
+3. **アプリケーションを通常どおり実行する。** `GOOGLE_APPLICATION_CREDENTIALS`
+   と `HIKOUTEI_SYNC_SPREADSHEET_URL` を設定した状態でアプリを起動すると、
+   `createTypedSheets()` がそれを検出して内部 sync bootstrap を開始します —
+   登録済みタブのヘッダーを作成・検証した後、outbox 配信と User_Input
+   ポーリングを開始します。渡す provider オプションも、手動で開始する内部
+   bootstrap もありません。
+
+> **レガシースプレッドシートの注意。** 旧 Apps Script provider が developer
+> metadata の行アンカーでプロビジョニングしたスプレッドシートは移行されませ
+> ん。`User_Input` タブは `__hikoutei_row_id` システム列を必要とするため、
+> レガシータブは再プロビジョニングが必要です。
 
 Hikoutei は、永続的なローカル outbox・冪等な配信・競合を考慮した更新を使う
 ため、一時的な API 障害でコミット済みのアプリケーション書き込みが失われる
@@ -211,8 +222,11 @@ Hikoutei は活発に開発中です。現在の EntityManager は、スカラ
 `limit` / `offset` ページネーション、コールバック形式の `transactional()` を
 サポートします。通常の読み取り元は常に SQLite であり、Google Sheets では
 ありません。
-シート編集の取り込みと競合表示はまだ発展途上です。マイナーバージョンの
-アップグレード前にリリースノートを確認してください。
+`hikoutei setup` CLI がスプレッドシートとサービスアカウントをプロビジョニ
+ングし、direct Google Sheets API provider(環境変数による自動開始)が唯一の
+同期経路です — Apps Script ゲートウェイはありません。シート編集の取り込みと
+競合表示はまだ発展途上です。マイナーバージョンのアップグレード前にリリース
+ノートを確認してください。
 
 ## ロードマップ
 
@@ -245,7 +259,6 @@ EntityManager のロードマップは、以下の実装順序に従います。
 
 - Google Sheets からの意図的なユーザー編集の取り込みを完了する
 - 更新・削除の競合処理と表示を改善する
-- レジストリと direct-provider デプロイのセットアップツールを改善する
 
 現在の作業は[オープンな Issues](https://github.com/ManddarinShop/Hikoutei/issues)を
 参照してください。

package/README.ko.md

@@ -118,9 +118,11 @@ Hikoutei는 `google-spreadsheet`나 `@googleapis/sheets`를 대체하지 않습
 
 Google Sheets 동기화는 서비스 측 관심사입니다. 애플리케이션은 provider
 클라이언트를 import하거나, Sheet 라우트를 `createTypedSheets()`에 넘기거나,
-쓰기마다 연산을 선택하지 않습니다. 동기화 런타임은 서비스 계정을 사용하는
-하나의 Google Sheets API provider(내부 `googleSheetsApi` bootstrap 옵션)를
-사용합니다 — Apps Script 배포가 없습니다.
+쓰기마다 연산을 선택하지 않습니다 — 루트 API는 `dbName`과 `entities`만
+받습니다. 동기화 런타임은 서비스 계정을 사용하는 하나의 내부 Google Sheets
+API provider를 사용합니다 — Apps Script 배포가 없습니다. 동기화 자동 시작은
+`HIKOUTEI_SYNC_SPREADSHEET_URL`과 `GOOGLE_APPLICATION_CREDENTIALS`로
+선택되며, 설정할 공개 `googleSheetsApi` bootstrap 옵션은 없습니다.
 
 ### 환경 변수 기반 동기화 자동 시작
 
@@ -142,7 +144,7 @@ const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities
 없거나 잘못된 자격 증명 파일, 스프레드시트에 공유되지 않은 서비스 계정
 (어떤 이메일을 공유해야 하는지 에러가 알려줍니다).
 
-### Service-account provider (googleSheetsApi)
+### 수동 서비스 계정 설정
 
 1. **서비스 계정을 만듭니다.** Cloud 프로젝트에서 Google Sheets API를
    활성화하고, `https://www.googleapis.com/auth/spreadsheets` 스코프의
@@ -152,9 +154,16 @@ const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities
 2. **키를 서버 측에 둡니다.** 서비스 계정 키 경로를 서버의
    `GOOGLE_APPLICATION_CREDENTIALS`에, 스프레드시트 ID는 추적되지 않는
    비밀 저장소에 둡니다. 키를 브라우저 코드나 Git에 넣지 마세요.
-3. **내부 sync bootstrap을 기동합니다.** `googleSheetsApi`를 설정하면
+3. **애플리케이션을 정상적으로 실행합니다.** `GOOGLE_APPLICATION_CREDENTIALS`와
+   `HIKOUTEI_SYNC_SPREADSHEET_URL`을 설정한 상태로 앱을 시작하면
+   `createTypedSheets()`가 이를 감지해 내부 sync bootstrap을 시작합니다 —
    등록된 탭의 헤더를 만들고 검증한 뒤 outbox 전달과 User_Input 폴링을
-   시작합니다.
+   시작합니다. 넘길 provider 옵션이나 직접 시작할 내부 bootstrap은 없습니다.
+
+> **레거시 스프레드시트 참고.** 이전 Apps Script provider가 developer
+> metadata 행 anchor로 프로비저닝한 스프레드시트는 마이그레이션되지
+> 않습니다. `User_Input` 탭은 이제 `__hikoutei_row_id` 시스템 컬럼이
+> 필요하므로 레거시 탭을 다시 프로비저닝해야 합니다.
 
 Hikoutei는 내구성 있는 로컬 outbox, 멱등 전달, 충돌을 인지하는 업데이트를
 사용하므로 일시적인 API 실패가 커밋된 애플리케이션 쓰기를 잃게 하지 않습니다.
@@ -204,7 +213,10 @@ MikroORM은 구현 세부 사항이며 Hikoutei의 공개 엔티티 API에는
 Hikoutei는 활발히 개발 중입니다. 현재 EntityManager는 스칼라 엔티티의 생명주기
 작업, 동등 조건을 사용하는 `find()` / `findOne()`, `find()`의 `limit` /
 `offset` 페이지네이션, 콜백형 `transactional()`을 지원합니다. 일반 읽기는
-Google Sheets가 아니라 항상 SQLite에서 수행됩니다. 시트 편집 수집과 충돌 표시는
+Google Sheets가 아니라 항상 SQLite에서 수행됩니다. `hikoutei setup` CLI가
+스프레드시트와 서비스 계정을 프로비저닝하며, direct Google Sheets API
+provider(환경 변수 자동 시작)가 유일한 sync 경로입니다 — Apps Script
+gateway가 없습니다. 시트 편집 수집과 충돌 표시는
 아직 발전 중입니다. 마이너 버전 업그레이드 전에 릴리스 노트를 확인하세요.
 
 ## 로드맵
@@ -238,7 +250,6 @@ EntityManager 로드맵은 아래 구현 순서를 따릅니다. 단계 순서
 
 - Google Sheets에서 의도적인 사용자 편집 수집 완성
 - 업데이트·삭제 충돌 처리와 표시 개선
-- 레지스트리 및 direct-provider 배포를 위한 설정 도구 개선
 
 현재 작업은 [오픈 이슈](https://github.com/ManddarinShop/Hikoutei/issues)를
 참고하세요.

package/README.md

@@ -121,9 +121,11 @@ client directly.
 
 Google Sheets synchronization is a service-side concern. Applications do not
 import a provider client, pass Sheet routes to `createTypedSheets()`, or choose
-an operation for each write. The sync runtime uses one Google Sheets API
-provider (the internal `googleSheetsApi` bootstrap option) with a service
-account — no Apps Script deployment.
+an operation for each write — the root API accepts only `dbName` and
+`entities`. The sync runtime uses one internal Google Sheets API provider with
+a service account — no Apps Script deployment. Sync auto-start is selected by
+`HIKOUTEI_SYNC_SPREADSHEET_URL` plus `GOOGLE_APPLICATION_CREDENTIALS`; there is
+no public `googleSheetsApi` bootstrap option to configure.
 
 **Fastest path:** install the gcloud CLI, then run `npx hikoutei setup` from your
 project directory. On an interactive terminal it offers (press Enter) to
@@ -224,7 +226,7 @@ local-only (SQLite). Startup failures are diagnosed with clear messages:
 invalid URL, missing/invalid credentials file, or a service account not
 shared on the spreadsheet (the error tells you which email to share).
 
-### Service-account provider (googleSheetsApi)
+### Manual service-account setup
 
 1. **Create a service account.** Enable the Google Sheets API in a Cloud
    project, create a service account with the
@@ -239,9 +241,17 @@ shared on the spreadsheet (the error tells you which email to share).
    `.gitignore` — the defaults created by `hikoutei setup` are already
    ignored, but a `.gitignore` is not a security boundary and does not
    protect already-tracked files.
-3. **Start the internal sync bootstrap** with `googleSheetsApi` configured. It
-   creates and verifies headers on the registered tabs, then starts outbox
-   delivery and User_Input polling.
+3. **Run the application normally.** Start the app with
+   `GOOGLE_APPLICATION_CREDENTIALS` and `HIKOUTEI_SYNC_SPREADSHEET_URL` set;
+   `createTypedSheets()` detects them and starts the internal sync bootstrap —
+   it creates and verifies headers on the registered tabs, then starts outbox
+   delivery and User_Input polling. There is no provider option to pass and no
+   internal bootstrap to start by hand.
+
+> **Legacy spreadsheet note.** Spreadsheets provisioned by the old Apps Script
+> provider with developer-metadata row anchors are not migrated: `User_Input`
+> tabs now require the `__hikoutei_row_id` system column, so legacy tabs must
+> be re-provisioned.
 
 Hikoutei uses a durable local outbox, idempotent delivery, and conflict-aware
 updates so temporary API failures do not lose committed application writes. The
@@ -293,9 +303,11 @@ Hikoutei is in active development. The current EntityManager supports scalar
 entity lifecycle operations, equality-filtered `find()` / `findOne()`,
 `limit` / `offset` pagination on `find()`, and callback-style
 `transactional()` work.
-Normal reads always come from SQLite, never Google Sheets. Sheet edit ingestion
-and conflict presentation are still evolving. Review release notes before
-upgrading minor versions.
+Normal reads always come from SQLite, never Google Sheets. The `hikoutei
+setup` CLI provisions the spreadsheet and service account, and the direct
+Google Sheets API provider (env-driven auto-start) is the only sync path — no
+Apps Script gateway. Sheet edit ingestion and conflict presentation are still
+evolving. Review release notes before upgrading minor versions.
 
 ## Roadmap
 
@@ -329,7 +341,6 @@ The following work continues in parallel with the EntityManager milestones:
 
 - Complete ingestion of intentional user edits from Google Sheets.
 - Improve update/delete conflict handling and presentation.
-- Improve setup tooling for registry and direct-provider deployment.
 
 See the [open issues](https://github.com/ManddarinShop/Hikoutei/issues)
 for current work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hikoutei",
-  "version": "0.5.21",
+  "version": "0.5.22",
   "description": "Typed repository and safe write layer for Google Sheets-backed MVPs. SQLite-authoritative entity lifecycle with asynchronous Google Sheets projection.",
   "repository": {
     "type": "git",