Skip to content

QUICKSTART-DEV.adoc

Latest commit

 

History

History
125 lines (97 loc) · 3.41 KB

QUICKSTART-DEV.adoc

File metadata and controls

125 lines (97 loc) · 3.41 KB
Raw

or: rescript build && cd wasm && cargo build --release --target wasm32-unknown-unknown, just test

ubicity — Quick Start for Developers

Tech Stack

Deno (TypeScript) + ReScript + Rust/WASM + Idris2 (ABI proofs) + JSON Schema — see README.adoc for overview

Set Up Development Environment

Option A: Guix (preferred)

guix shell

Option B: Nix (fallback)

nix develop

Option C: Manual

git clone https://github.com/hyperpolymath/ubicity.git
cd ubicity
just setup-dev

Build

just build
# or: rescript build && cd wasm && cargo build --release --target wasm32-unknown-unknown

Test

just test
# or: deno test --allow-read --allow-write tests/
# Idris2 tests: just test-core (requires idris2 0.8.0+)

Project Structure

ubicity/
├── src/                  # Source code
├── src/abi/              # Idris2 ABI definitions (if applicable)
├── ffi/zig/              # Zig FFI bridge (if applicable)
├── tests/                # Test suite
├── docs/                 # Documentation
├── .machine_readable/    # Checkpoint files (STATE, META, ECOSYSTEM)
├── Justfile              # Task runner recipes
├── guix.scm              # Guix environment
├── flake.nix             # Nix environment (fallback)
└── 0-AI-MANIFEST.a2ml    # AI agent entry point

Key Recipes

just build          # Build the project
just test           # Run tests
just doctor         # Self-diagnostic
just lint           # Lint and format
just panic-scan     # Security scan via panic-attacker
just tour           # Guided tour of the codebase

Before Submitting a PR

just lint           # Format and lint
just test           # All tests pass
just panic-scan     # No new security issues

Contractile Invariants

Read .machine_readable/MUST.contractile before making changes. Key invariants that must never be violated:

  • No hardcoded absolute paths — use env vars, XDG dirs, or relative references

  • No new TypeScript/Python/Go files — Deno-only for JS/TS, ReScript for frontend, Rust for WASM

  • No npm/bun/yarn/pnpm — Deno only

  • No believe_me / assert_total (Idris2), no Admitted/sorry/unsafeCoerce

  • SPDX-License-Identifier header on every source file

  • .machine_readable/ directory and 0-AI-MANIFEST.a2ml preserved

  • No removal of CI workflows without approval, all GitHub Actions SHA-pinned

  • Tests must not be deleted or weakened, generated code only in generated/

  • No OWASP top 10, no modification of ABI contracts without proof update

LLM/AI Agent Development

If using an AI assistant, load the warmup context first:

just llm-context    # Outputs role-appropriate context

Or read 0-AI-MANIFEST.a2ml and .claude/CLAUDE.md directly.

Get Help