Skip to content

README.md

Latest commit

 

History

History
199 lines (151 loc) · 9.72 KB

README.md

File metadata and controls

199 lines (151 loc) · 9.72 KB
Raw

JCode — Engineering Specifications

As-built specifications for JCode, a native Android IDE with an embedded Linux runtime.
Product version 1.7.7 (app/build.gradle.kts, val jcodeVersion)
Verified against commit cea581c, 2026-08-09
Scope The whole system: 43 Gradle modules across :app, :core:*, :feature:*, :native:*

What these documents are

These specs describe what the system actually is today, derived from the source tree — not what it was planned to be. Where an intended design was never wired up, the spec says so in place rather than describing the intent as if it shipped — each document closes with its own "Known gaps" section, so the caveat sits beside the thing it qualifies.

They are not a requirements document. There are no SHALL statements and no requirement IDs; nothing here is a promise about future behavior.

These documents supersede the system description embedded in AGENTS.md, which has drifted in places. AGENTS.md remains authoritative for how to work in this repo (conventions, locked decisions, verification commands).

Reading order

New to the codebase — read in this order:

  1. Product overview
  2. Glossary and conventions
  3. System architecture
  4. Module map
  5. Storage and path model
  6. …then whichever subsystem you are touching.

Looking for a specific on-disk format — go straight to the File format index.

Contents

00 — Overview

Document Covers
01 Product overview What JCode is, capability surface, non-goals
02 Glossary and conventions Distro, rootfs, guest, workspace, project, .jext, Dev Pack, and this document set's conventions

01 — Architecture

Document Covers
01 System architecture Layers, the three processes, Android platform constraints
02 Module map All 43 Gradle modules, the dependency rule, stub inventory
03 Concurrency and resource lifecycle Dispatchers, single-writer editor, Cleaner, ResourceManager
04 Native layer and JNI CMake superbuild, Cargo path, .so ↔ class ↔ export table
05 Storage and path model On-device layout, host↔guest path translation, SAF boundary

02 — Editor

Document Covers
01 Text buffer Buffer, Snapshot, piece table / native piece tree, edit transactions
02 Editor state and undo EditorState flows, carets, folds, viewport, UndoManager
03 Rendering and decorations Renderer, WrapMap, decoration layers, dirty tracking
04 Input, IME and gestures EditorView, InputConnection, selection handles, column encodings
05 Syntax highlighting and completion The real highlight path, the unwired tree-sitter stack, completions and snippets

03 — Runtime

Document Covers
01 Terminal, PTY and VT PtyProcess, VtParser, session manager, terminal view
02 Shell integration protocol OSC 7711–7716 and OSC 52 — exact payloads
03 Embedded Linux runtime proot invocation, rootfs lifecycle, synthetic /proc
04 Toolchain catalog and onboarding catalog.yaml schema and entries, setup state machine
05 ADB bridge ADB transport frames, auth, daemon/relay/discovery

04 — Language services

Document Covers
01 LSP client Framing, handshake, server catalog, diagnostics bus
02 Debug Adapter Protocol DAP framing, handshake order, reverse requests, engine catalog
03 Search and source control ripgrep FFI and fallback, search scopes, the SCM panel

05 — Workspace and configuration

Document Covers
01 Workspaces and projects Room schema, workspace operations, breadcrumbs, SAF vs local
02 Configuration model Workspace/project YAML, merge to effective config, live reload
03 Run and build configurations run.yaml v1/v2, the runner, ready-port preview, debug handoff

06 — Workbench

Document Covers
01 Shell layout and navigation Modal vs docked drawers, sizing, orientation, session restore
02 Editor tabs and pages Tab model, page kinds, groups, pinning, close guards
03 Panels and tools Left/right drawer tools, command palette, key bindings
04 Settings reference Scope tabs, groups, every key and default
05 Design system Theme bundles, UI/file icon sets, tokens, contrast rules

07 — Extensions

Document Covers
01 Extension model and lifecycle Types, activation, capabilities, install/update, dependencies
02 .jext package format Byte layout, signing, encryption, manifest fingerprint
03 Manifest reference Every extension.yaml key and contribution point
04 Extension API and hosts The WebView bridge, and the .vsix Node host protocol
05 Templates and scaffolding Template model, recipe steps, inputs, token substitution

08 — Virtual device

Document Covers
01 App sandbox architecture The :guest process, embedded vs full-screen, AIDL surface
02 Guest runtime and hidden API Class loading, identity, hooks, hidden-API table, input injection
03 Android app debugging Module detection, JDWP forwarding, attach flow

09 — Platform

Document Covers
01 File format index Every on-disk artifact JCode reads or writes
02 Build variants and release Toolchain versions, variants, version codes, signing
03 CI, quality and invariants The no-host-root scanner, code-quality rules, verification commands
04 Security and privacy Trust model, sandbox boundaries, permissions, log hygiene

Document conventions

Every specification uses the same shape:

# <Title>

| | |
|---|---|
| **Status** | Implemented / Partially implemented / Built but unwired / Stub |
| **Modules** | `:core:x`, `:native:y` |
| **Primary sources** | path/one.kt, path/two.cpp |
| **Verified against** | commit <sha>, <date> |

## 1. Purpose and scope
## 2. Architecture
## 3. Public contract
## 4. Data model
## 5. Behavior
## 6. Protocol / format        (only where one exists)
## 7. Threading and lifecycle
## 8. Invariants and constraints
## 9. Failure modes
## 10. Known gaps
## 11. References

Sections that do not apply to a subsystem are omitted rather than left empty; the numbering stays stable so ## 6 always means "protocol or format" where it appears.

Status values

Status Meaning
Implemented Present and reachable from normal app use
Partially implemented Reachable, with named behavior missing
Built but unwired Code compiles and works in isolation; nothing calls it
Stub A marker type or empty module with no behavior

Rules these documents follow

  • Every factual claim is traceable to a repo-relative source path. Non-obvious claims cite path:line.
  • Enum members, defaults, ports, flags and magic numbers are copied from source, never paraphrased or recalled.
  • Cross-references between specs are relative Markdown links.
  • Mermaid diagrams appear only where a picture beats prose — process topology, protocol handshakes, binary layouts, launch flows.
  • Line numbers drift. Symbol names and file paths are the durable anchors; treat a cited line as a hint, not a contract.

Maintaining these documents

  • A change that alters a protocol, on-disk format, module boundary, or public contract should update the corresponding spec in the same change.
  • After a substantial edit, re-run the checks in CI, quality and invariants: every source path cited by a spec must still exist, and every relative spec link must resolve.
  • Update the Verified against row of any document you re-check against source.