Metadata-Version: 2.4
Name: symboliclight
Version: 1.0.0
Summary: Spec-native, AI-friendly language for typed CLI and backend apps.
Author: SymbolicLight Contributors
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Provides-Extra: intentspec
Requires-Dist: intentspec>=0.1.0; extra == "intentspec"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "postgres"
Dynamic: license-file

# SymbolicLight

SymbolicLight Language, or SL, is a spec-native, AI-friendly application language for building typed CLI and backend apps with less glue code.

It is designed for developers who want application code that is easy for humans and AI tools to generate, review, test, and maintain. SL v1.0 focuses on explicit models, stores, routes, commands, tests, and task-spec alignment.

SymbolicLight is not trying to replace Python, Rust, or TypeScript everywhere. Its first goal is narrower:

> Write application intent, data models, storage, routes, commands, and tests in one compact source file.

SL compiles to readable Python 3.11 so generated apps can run on the existing Python ecosystem.

## Naming

- Formal project and brand name: SymbolicLight.
- Developer-facing language name: SL.
- Compiler command: `slc`.
- Source file extension: `.sl`.

Use SymbolicLight in project, website, release, and positioning text. Use SL in developer docs, examples, tutorials, and day-to-day language references.

## Current Stable Baseline

SL v1.0 supports:

- `app` declarations.
- `module` declarations and explicit `import "./file.sl" as name`.
- `intent "./file.intent.yaml"` links to IntentSpec contracts.
- `permissions from intent.permissions` and `test from intent.acceptance` declarations.
- `enum` declarations and `type` record declarations.
- pure `fn` declarations inside modules and apps.
- `Option<T>` and `Result<T, E>` type references.
- `store` declarations backed by SQLite or optional Postgres.
- `command` handlers compiled to CLI subcommands.
- `route GET/POST/PUT/PATCH/DELETE` handlers compiled to JSON HTTP routes.
- typed route bodies and `Response<T>` status responses.
- `fixture` declarations and golden tests.
- typed `config` declarations.
- SQLite helpers such as `count`, `exists`, and test-only `clear`.
- JSON schema generation through `slc schema`.
- `test` blocks compiled to lightweight Python assertions.
- official formatting through `slc fmt`.
- source-map sidecars and best-effort `.sl` runtime backreferences.
- incremental `slc check` cache reuse.
- JSON diagnostics for tools through `slc check --json`.
- machine-readable doctor reports through `slc doctor --json`.
- read-only migration plans through `slc migrate plan`.
- local LSP support through `slc lsp`.
- local VS Code syntax, snippets, and language-server wiring under `editors/vscode`.
- local playground under `playground/`.
- IntentSpec-aware `slc doctor` route, command, and permission alignment hints.
- IntentSpec acceptance checks through `slc test` for apps that declare `test from intent.acceptance`.
- route auth checks through the minimal `request.header(...)` helper.
- schema drift inspection through `slc doctor --db`.
- optional Postgres runtime support through `symboliclight[postgres]`.
- comment-preserving formatting for common `//` comment positions.
- repeatable release smoke checks through `scripts/release_check.py`.
- starter API templates through `slc new api --template`.
- docs, VS Code, and release notes maintenance checks.

## Quick Start

Install from a local checkout for development:

```bash
pip install -e ".[dev]"
```

After building a local v1.0 package, install the wheel directly:

```bash
python -m build
pip install dist/symboliclight-1.0.0-py3-none-any.whl
slc check examples/todo_app.sl
slc check examples/todo_app.sl --json
slc build examples/todo_app.sl --out build/todo_app.py
slc schema examples/notes_api.sl --out build/notes_schema.json
slc fmt examples/todo_app.sl --check
slc doctor examples/todo_app.sl
slc doctor examples/todo_app.sl --json
slc doctor examples/gallery/small-admin-backend/app.sl --db build/admin.sqlite
slc doctor examples/gallery/small-admin-backend/app.sl --db build/admin.sqlite --json
slc migrate plan examples/gallery/project-ops-api/app.sl --db build/project_ops.sqlite
slc check examples/gallery/project-ops-api/app_postgres.sl
slc new api my-api --template todo --backend sqlite
slc new api ops-api --template project-ops --backend postgres
slc lsp
python build/todo_app.py test
python build/todo_app.py add "Buy milk"
python build/todo_app.py list
python build/todo_app.py serve
```

SQLite generated apps use only the Python standard library: `argparse`, `sqlite3`, `http.server`, and `json`. Postgres generated apps require installing `symboliclight[postgres]`.

## 10-minute Trial Path

```bash
slc check examples/todo_app.sl
slc build examples/todo_app.sl --out build/todo_app.py
python build/todo_app.py test
python build/todo_app.py add "Buy milk"
slc new api my-api --template todo --backend sqlite
slc check my-api/src/app.sl
```

For a guided first app, read [Build a Todo App](docs/site/tutorial.md). For a compact syntax overview, read [Language Tour](docs/site/language-tour.md).

## Example

```sl
app TodoApp {
  intent "./todo.intent.yaml"

  type Todo = {
    id: Id<Todo>,
    title: Text,
    done: Bool,
  }

  store todos: Todo

  command add(title: Text) -> Todo {
    return todos.insert({ title: title, done: false })
  }

  route GET "/todos" -> List<Todo> {
    return todos.all()
  }
}
```

Typed request bodies and status responses:

```sl
route POST "/notes" body CreateNote -> Response<Note> {
  let note = notes.insert({ title: request.body.title, body: request.body.body })
  return response(status: 201, body: note)
}
```

Multi-file apps use explicit imports:

```sl
module models {
  enum Status { open, closed }

  type Issue = {
    id: Id<Issue>,
    title: Text,
    status: Status,
    assignee: Option<Text>,
  }

  fn is_open(status: Status) -> Bool {
    return status == Status.open
  }
}
```

```sl
app IssueTracker {
  import "./models.sl" as models

  store issues: models.Issue

  command create(title: Text) -> models.Issue {
    return issues.insert({ title: title, status: models.Status.open })
  }

  route GET "/open" -> Bool {
    return models.is_open(models.Status.open)
  }
}
```

## Relationship With IntentSpec

IntentSpec describes task intent, permissions, output contracts, and acceptance tests.

SymbolicLight implements the application.

Together:

```text
IntentSpec = what should be built and how it is accepted
SymbolicLight = the application implementation
```

IntentSpec validation is optional in normal `slc check` runs. If the `intentspec` package is installed, SL validates referenced intent files. Missing IntentSpec support is reported as a warning unless `--strict-intent` is used.

When an app declares `test from intent.acceptance`, `slc test` runs a v0.6 offline acceptance bridge after generated app tests pass. It checks SL route and command hints, permission mismatches, and `required_sections` assertions from the IntentSpec output contract.

## Commands

```bash
slc check <file.sl>
slc check <file.sl> --json
slc check <file.sl> --no-cache
slc build <file.sl> --out build/app.py
slc build <file.sl> --out build/app.py --no-source-map
slc schema <file.sl> --out build/schema.json
slc run <file.sl> -- add "Buy milk"
slc test <file.sl>
slc fmt <file.sl>
slc doctor <file.sl>
slc doctor <file.sl> --json
slc doctor <file.sl> --db path/to/app.sqlite
slc doctor <file.sl> --db path/to/app.sqlite --json
slc migrate plan <file.sl> --db path-or-url
slc new api <name> --template todo --backend sqlite
slc new api <name> --template project-ops --backend postgres
slc lsp
slc init <dir>
slc new api <name>
slc add route GET /items <file.sl>
```

## Release Check

```bash
python scripts/release_check.py --skip-package
python scripts/docs_check.py
python scripts/vscode_check.py
python scripts/freeze_check.py
python scripts/example_matrix.py
python -m build
python scripts/package_smoke.py --gallery
python scripts/release_notes.py --from v0.13.0-rc2 --to HEAD --out build/release-notes-v1.0.0.md
python scripts/release_check.py
```

For the local `v1.0.0` baseline, run the full release check from a clean worktree. The check builds a local wheel, installs it into a temporary environment, runs installed `slc` against the gallery, exercises a `doctor --db` fixture where the stored schema hash matches but the SQLite structure is missing a column, runs migration-plan smoke checks, and runs compatibility fixtures for prior v0.x examples. No GitHub, TestPyPI, or PyPI upload is performed by these commands.

## Project Status

This repository is prepared as a local v1.0 stable baseline. The goal is to keep typed backend and CLI apps compact, testable, and AI-friendly while still producing readable, runnable Python. Public redistribution is a separate owner decision after reviewing the local release artifacts.
