Dataless

Dataless rewrites Formless's data layer; Formless is intended to become its UI. A portable JSON Program defines typed Records and Operations. The Authority owns validation, transactions, and durable storage.

The current runtime is Bun with SQLite, built with Effect. Cloudflare is deferred.

Documentation

• AGENTS.md: working rules and the spec ownership map.
• spec/: agent-facing contracts for implemented behavior.
• todo/: agent-facing workstreams, remaining proposals, and dependencies.

User-facing guides are deferred until there is an audience.

Codeless runs capability work from todo/, integrates through main, and leaves dev for personal development.

Contributor quick start

Install Bun before starting. From the repository root in the first terminal:

bun install
bun run dev

This starts the server in the ignored tmp/ directory with Bun watch mode. Wait for the readiness message before connecting. Source changes restart the process; the installed Program and data persist.

In a second terminal, also starting from the repository root:

cd tmp
bun ../bin/dataless describe
bun ../bin/dataless operations

These commands use the running project's RPC endpoint. A new project starts with an empty Program, so an empty Operation list is expected. Connect an MCP client to define Records, Fields, and Operations. Example JSON files are not automatically loaded by serve.

Commands discover the nearest ancestor containing .dataless/, so run them inside the intended project. Without an existing ancestor project, serve creates one in its working directory. In project mode, client commands require an existing project and do not start the server.

The default listener is 127.0.0.1:3765, with RPC at /rpc and MCP at /mcp. A port conflict fails startup; serve --port provides a development override. Use the endpoints printed at startup when overriding the port.

For command help, from the repository root:

bun run dataless --help

See Clients and transports for invocation inputs, results, and explicit database/remote targeting.

Connect an MCP client

Use a client on the same machine as the server. From the second terminal, still in tmp/, retrieve the existing owner token:

bun ../bin/dataless token

Configure the client with:

| Setting | Value | | -------------------- | ----------------------------------------------- | | Transport | Streamable HTTP | | URL | http://127.0.0.1:3765/mcp | | Authorization header | Bearer <token>, using the token printed above |

The token command prints a secret. Keep it out of committed configuration and URLs; use the client's secret or environment-variable support where available. A desktop client must receive any referenced environment variable in its own process environment.

This is a local, same-user development setup. A client on another machine cannot reach this loopback address. The endpoint is served by the running project server.

See MCP contracts for discovery and invocation, and semantic edits for authoring.

Checks

Run checks from the repository root:

bun run smoke
bun run check

smoke runs the project workflow tests: temporary projects, authenticated RPC/MCP, CLI use, persistence, and restart. The tests stop their servers and remove their temporary state.

check runs Dataless's TypeScript, lint, formatting, and tests, with automatic fixes. Review any resulting file changes. For tests alone, use bun test. Server tests require local loopback listeners.

Release

From a clean main checkout, publish the next patch release with:

bun run release

The script verifies npm authentication, runs the full check and an npm package dry run, increments the patch version, commits package.json with the version as the complete commit message, creates a matching v<version> tag, and publishes @dpeek/dataless. It intentionally does not push the commit or tag.

For non-interactive local publishing, create an npm granular access token with read/write access to @dpeek/dataless (or the @dpeek scope) and Bypass 2FA enabled. Keep it outside the repository, for example in your user-level ~/.npmrc:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Put the token itself in the repository's ignored .env file:

NPM_TOKEN=npm_your_token_here

bun run release loads .env and passes the token to npm. Never put the token directly in a committed .npmrc or source file.

If npm package settings disallow tokens, publishing will still require an OTP. For hosted CI, prefer npm trusted publishing instead of a long-lived token.

Examples and evaluations

• Tasks Program: a small portable definition.
• Issue model: a larger modeling example.
• Issue-model evaluation: an agent authoring exercise.
• Project workflow tests: executable examples of serving a project and using CLI/MCP.

Local state

The development project normally keeps its database, installed Program, receipts, and owner credential under tmp/.dataless/. Connection metadata records the current listener addresses. The repository ignores tmp/ and its root .dataless/; ignore .dataless/ yourself in other project repositories.

Stop the development server with Ctrl+C. Restarting preserves its Program, data, and token. To reset a disposable development project, stop every process using it, then delete tmp/.dataless/. This permanently removes its data and token; update the MCP client credential after creating the replacement project.

See Project and storage for the lifecycle and storage contracts.

Backing up a database

There is no Dataless backup command. For a live database, use SQLite-aware tooling such as the SQLite backup API or VACUUM INTO.

For a file copy, stop all processes using the database and wait for clean exit. Do not copy only the main database while writes may be active. After an unclean stop, a -wal file may hold committed data: keep it paired with its database and recover through SQLite before making a clean backup. Do not discard or mix WAL files from different databases. See SQLite's backup and recovery guidance.