Hikoutei: Instructions file for Codex

AGENTS.md

Project

Hikoutei (npm/import name hikoutei) is a TypeScript library that uses a local SQLite entity store as the application authority and exposes Google Sheets as an asynchronous human-facing projection for MVP apps, internal tools, prototypes, and low-traffic admin workflows.

Use this positioning:

Typed repository and safe write layer for Google Sheets-backed MVPs.

Do not describe the project as a database replacement, a Prisma/JPA clone, a general-purpose Google Sheets API wrapper, or a transaction-safe database on top of Sheets. SQLite is the authority; Sheets is an async projection and human input surface, not the source of truth.

The authoritative design lives in docs/architecture.md, docs/write-and-synchronization-flow.md, docs/internal-consistency-model.md, and docs/code-guidelines.md. Note that docs/ (like design/) is gitignored and local-only — it is not tracked or shipped — so those links resolve only in local checkouts; keep source consistent with the documents when present.

Public API direction

The public API is an entity-lifecycle EntityManager modeled on the MikroORM/JPA workflow. Applications define entities with defineTypedSheetsEntity() and open the runtime with createTypedSheets(), then use a request-local manager for fork(), create(), find(), findOne(), count(), findAndCount(), persist(), remove(), flush(), and transactional():

import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";

const User = defineTypedSheetsEntity({
  name: "User",
  tableName: "users",
  properties: { id: { type: "string", primary: true }, name: { type: "string" } },
});
const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities: [User] });

const em = hikoutei.em.fork();
const user = em.create(User, { id: "u1", name: "Ada" });
em.persist(user);
await em.flush();

user.name = "Ada Lovelace";
await em.flush();