Zeptoz

Appearance

Bootstrap & Generated Artifacts ​

This is the canonical source for what Zeptoz creates in filesystem and database when using setup commands.

What zeptoz init does ​

Command:

bash
zeptoz init <project_name>

Generates:

  • Project directories:
    • data/
    • hooks/
    • storage/
  • Config file:
    • zeptoz.toml
  • Runtime side effect:
    • connects to configured DB and applies migrations

Why it exists:

  • establishes a deterministic project contract before runtime
  • avoids implicit startup writes in production paths
  • provides repeatable local/CI bootstrap

Init ​

bash
zeptoz init <project_name>

Filesystem:

  • <project>/data/
  • <project>/hooks/
  • <project>/storage/
  • <project>/zeptoz.toml

Database:

  • migration-managed tables are created if missing

Runtime effect:

  • DB connect, migrations apply, health check

Collection Create ​

bash
zeptoz collection create <name> [fields...]

Filesystem:

  • none (default behavior)

Database:

  • row in schema_collections
  • rows in schema_fields (one per field)
  • physical table col_<name>

Runtime effect:

  • collection becomes available for CRUD and OpenAPI generation

Collection Create With Hook ​

bash
zeptoz collection create <name> [fields...] --with-hook <event>:<lang>:<name>

Filesystem:

  • hook source scaffold (if scaffold mode is used)
  • JS/TS artifact when language is JS/TS
  • TS types file when language is TS

Database:

  • same collection metadata as collection create
  • row in hook_definitions
  • row in hook_bindings

Runtime effect:

  • hook binding becomes resolvable by event/collection

Collection Policy Set ​

bash
zeptoz collection policy set <name> [--list-policy ...] [--view-policy ...] [--create-policy ...] [--update-policy ...] [--delete-policy ...]

Filesystem:

  • none

Database:

  • updates collection policy columns

Runtime effect:

  • subsequent requests enforce updated collection policies

Relation Add ​

bash
zeptoz relation add <collection> <name> <belongs_to|has_one|has_many|many_to_many> <target> [options]

Filesystem:

  • none

Database:

  • row in schema_relations
  • for belongs_to/has_one:
    • ensures FK field metadata row in schema_fields (auto-creates <name>_id when missing)
    • adds FK column to physical source table col_<collection>
    • creates index on that FK column
  • for many_to_many:
    • creates/uses through table (default rel_<collection>_<name>)
    • records through_table, through_source_fk, through_target_fk in relation metadata

Runtime effect:

  • relation becomes available for API expand and relation filters
  • relation write semantics become active (belongs_to/has_one direct value, many_to_many edge ops)

Hook Add (Scaffold) ​

bash
zeptoz hook add <collection> <event> --lang <rs|ts|js|py> --new <name>

Filesystem:

  • source scaffold under hooks/<collection>/<event>/
  • JS/TS .compiled.js artifact when language is JS/TS
  • hooks/_sdk/types.d.ts when language is TS

Database:

  • row in hook_definitions
  • row in hook_bindings

Runtime effect:

  • hook binding becomes active for subsequent matching requests

Hook Add (Existing Source) ​

bash
zeptoz hook add <collection> <event> --lang <rs|ts|js|py> --source <path>

Filesystem:

  • uses existing source file
  • may write JS/TS compiled artifact

Database:

  • row in hook_definitions
  • row in hook_bindings

Runtime effect:

  • hook binding becomes active for subsequent matching requests

Runtime migrations behavior ​

At startup paths (dev and runtime server wiring), Zeptoz runs connect_and_migrate:

  1. resolve DB backend from database.url
  2. ensure SQLite parent directory exists (SQLite only)
  3. connect to DB
  4. apply pending migrations
  5. run health check (SELECT 1)

Migration runs are idempotent.

If you skip init ​

You must manually ensure all of the following are valid before runtime:

  • zeptoz.toml exists and is parseable
  • configured directories exist and are writable
  • database URL is valid and reachable
  • migration baseline can be applied successfully

For most workflows, init is the safer and more deterministic setup path.