Update package readmes, add init command

Author: gloomweaver

README.md

@@ -1,31 +1,65 @@
 # effql
 
 [![CI](https://github.com/gloomweaver/effql/actions/workflows/ci.yml/badge.svg)](https://github.com/gloomweaver/effql/actions/workflows/ci.yml)
+[![npm: @effql/cli](https://img.shields.io/npm/v/%40effql%2Fcli?label=%40effql%2Fcli)](https://www.npmjs.com/package/@effql/cli)
+[![npm: @effql/core](https://img.shields.io/npm/v/%40effql%2Fcore?label=%40effql%2Fcore)](https://www.npmjs.com/package/@effql/core)
 
 `effql` is a `sqlc`-style TypeScript code generator for `effect` / `@effect/sql`.
 
 It keeps a SQL-first workflow, uses Postgres introspection to infer types, and emits Effect-native code built around `Schema` and `SqlSchema.*`.
 
-## Why effql
+## Packages
 
-- write raw SQL in `.sql` files
-- keep familiar query annotations like `-- name: GetUser :one`
-- use TypeScript / JavaScript config via `defineConfig()` instead of YAML
-- infer result shapes from a real Postgres database
-- generate executable Effect wrappers instead of plain DTOs
+- [`@effql/cli`](https://www.npmjs.com/package/@effql/cli) — CLI package providing the `effql` command
+- [`@effql/core`](https://www.npmjs.com/package/@effql/core) — config loading, SQL parsing, Postgres analysis, and code generation
 
-## Status
+## Installation
 
-This is an early **Postgres-only MVP**.
+```bash
+npm install -D @effql/cli @effql/core
+```
 
-What works today:
+```bash
+pnpm add -D @effql/cli @effql/core
+```
 
-- TS / JS config via `defineConfig()`
-- query annotations: `:one`, `:maybeOne`, `:many`, `:exec`
-- named params via `@param`
-- Postgres-backed type inference
-- generated `Schema` exports and `SqlSchema.single/findOne/findAll/void` wrappers
-- self-contained CRUD example with Docker Compose and an Effect HTTP API
+## CLI usage
+
+Bootstrap a project:
+
+```bash
+npx @effql/cli init
+npx @effql/cli init --config ./effql.config.ts
+```
+
+This creates:
+
+- `effql.config.ts`
+- `sql/queries.sql`
+- `package.json` if one does not already exist
+
+Installed locally:
+
+```bash
+npx effql init
+npx effql generate
+npx effql generate --config ./effql.config.ts
+```
+
+One-off without installing:
+
+```bash
+npx @effql/cli generate
+npx @effql/cli generate --config ./effql.config.ts
+```
+
+Also works with pnpm:
+
+```bash
+pnpm dlx @effql/cli generate
+```
+
+Yes — `npx` works because `@effql/cli` publishes the `effql` bin.
 
 ## Quick start
 
@@ -48,19 +82,6 @@ Or run the full smoke test used by CI:
 pnpm run example:smoke
 ```
 
-## Workspace
-
-- `packages/core` — config loading, SQL parsing, Postgres analysis, code generation
-- `packages/cli` — `effql generate`
-- `examples/basic` — self-contained Postgres + generated CRUD module + Effect HTTP API
-
-## CLI
-
-```bash
-effql --help
-effql generate --config ./effql.config.ts
-```
-
 ## Config
 
 `effql` uses code-based config:
@@ -99,15 +120,12 @@ RETURNING id, email, created_at;
 SELECT id, email, created_at
 FROM users
 WHERE id = @id::uuid;
-
--- name: ListUsers :many
-SELECT id, email, created_at
-FROM users
-ORDER BY created_at DESC;
 ```
 
 ## Generated output shape
 
+Starter `sql/queries.sql` contains a simple `Healthcheck` query you can edit right away.
+
 Generated modules export:
 
 - `*ParamsSchema`
@@ -116,8 +134,6 @@ Generated modules export:
 - raw `*Sql` strings
 - executable `SqlSchema.*` wrappers
 
-Example:
-
 ```ts
 export const CreateUserResultSchema = Schema.Struct({
   id: Schema.UUID,
@@ -135,58 +151,28 @@ export const createUser = SqlSchema.single({
 });
 ```
 
-## Direct usage example
-
-You can call generated functions by providing a SQL client layer:
-
-```ts
-import { PgClient } from "@effect/sql-pg";
-import { Effect, Redacted } from "effect";
-import { createUser, listUsers } from "./generated/index.ts";
-
-const program = Effect.gen(function* () {
-  const created = yield* createUser({
-    id: "33333333-3333-3333-3333-333333333333",
-    email: "grace@example.com",
-  });
-
-  const users = yield* listUsers({});
-
-  return { created, users };
-});
-
-const runnable = program.pipe(
-  Effect.provide(
-    PgClient.layer({
-      url: Redacted.make("postgres://postgres:postgres@127.0.0.1:54329/postgres"),
-    }),
-  ),
-);
-```
-
-## Effect HTTP API example
-
-`examples/basic/src/httpApi.ts` wires generated CRUD queries into an Effect `HttpApi`.
+## Example project
 
-Routes:
+See `examples/basic` for the easiest end-to-end demo:
 
-- `POST /users`
-- `GET /users`
-- `GET /users/:id`
-- `PUT /users/:id`
-- `DELETE /users/:id`
+- `compose.yaml` starts Postgres on `127.0.0.1:54329`
+- `schema.sql` creates and seeds `users`
+- `sql/queries.sql` defines CRUD queries
+- `generated/index.ts` is committed generated output
+- `src/httpApi.ts` and `src/server.ts` show runtime usage
 
-Try it:
+## Status
 
-```bash
-curl http://127.0.0.1:3000/users
+This is an early **Postgres-only MVP**.
 
-curl http://127.0.0.1:3000/users/11111111-1111-1111-1111-111111111111
+What works today:
 
-curl -X POST http://127.0.0.1:3000/users \
-  -H 'content-type: application/json' \
-  -d '{"email":"grace@example.com"}'
-```
+- TS / JS config via `defineConfig()`
+- query annotations: `:one`, `:maybeOne`, `:many`, `:exec`
+- named params via `@param`
+- Postgres-backed type inference
+- generated `Schema` exports and `SqlSchema.single/findOne/findAll/void` wrappers
+- self-contained CRUD example with Docker Compose and an Effect HTTP API
 
 ## Known limitations
 
@@ -199,26 +185,15 @@ Current MVP limitations:
 - output is currently a single generated module per target
 - API / config shape may still evolve before a stable release
 
-## Validation and CI
-
-Current checks cover:
-
-- formatting and linting
-- workspace typechecking
-- unit tests
-- Postgres integration tests
-- example generation smoke test in GitHub Actions
-- example API smoke test via `pnpm run example:smoke`
-
 ## Publishing
 
 A GitHub Actions release workflow publishes the npm packages when a GitHub release is marked as `published`.
 
 Before using it:
 
-- add an `NPM_TOKEN` repository secret
+- add an `NPM_TOKEN` repository secret if you keep token-based publishing
 - make sure you own/publish to both `@effql/cli` and `@effql/core` on npm
-- create releases with tags that match the package versions, for example `v0.1.0`
+- create releases with tags that match the package versions, for example `v0.1.1`
 
 The release workflow:
 
@@ -228,23 +203,13 @@ The release workflow:
 - publishes `@effql/core`
 - publishes `@effql/cli`
 
-## Example project
-
-See `examples/basic` for the easiest end-to-end demo:
-
-- `compose.yaml` starts Postgres on `127.0.0.1:54329`
-- `schema.sql` creates and seeds `users`
-- `sql/queries.sql` defines CRUD queries
-- `generated/index.ts` is committed generated output
-- `src/httpApi.ts` and `src/server.ts` show runtime usage
-
-## Development commands
+## Development
 
 ```bash
 vp install
 vp lint
-vp run -r check
-vp run -r test
+vp fmt
+vp test
 vp run -r build
 pnpm run example:smoke
 ```

examples/basic/generated/index.ts

@@ -30,9 +30,10 @@ RETURNING id, email, created_at`;
 export const createUser = SqlSchema.single({
   Request: CreateUserParamsSchema,
   Result: CreateUserResultSchema,
-  execute: (request) => Effect.flatMap(SqlClient.SqlClient, (sql) =>
-    sql.unsafe(createUserSql, [request.id, request.email])
-  ),
+  execute: (request) =>
+    Effect.flatMap(SqlClient.SqlClient, (sql) =>
+      sql.unsafe(createUserSql, [request.id, request.email]),
+    ),
 });
 
 /**
@@ -61,9 +62,8 @@ WHERE id = $1::uuid`;
 export const getUser = SqlSchema.single({
   Request: GetUserParamsSchema,
   Result: GetUserResultSchema,
-  execute: (request) => Effect.flatMap(SqlClient.SqlClient, (sql) =>
-    sql.unsafe(getUserSql, [request.id])
-  ),
+  execute: (request) =>
+    Effect.flatMap(SqlClient.SqlClient, (sql) => sql.unsafe(getUserSql, [request.id])),
 });
 
 /**
@@ -90,9 +90,7 @@ ORDER BY created_at DESC`;
 export const listUsers = SqlSchema.findAll({
   Request: ListUsersParamsSchema,
   Result: ListUsersResultSchema,
-  execute: (request) => Effect.flatMap(SqlClient.SqlClient, (sql) =>
-    sql.unsafe(listUsersSql)
-  ),
+  execute: (request) => Effect.flatMap(SqlClient.SqlClient, (sql) => sql.unsafe(listUsersSql)),
 });
 
 /**
@@ -124,9 +122,10 @@ RETURNING id, email, created_at`;
 export const updateUser = SqlSchema.single({
   Request: UpdateUserParamsSchema,
   Result: UpdateUserResultSchema,
-  execute: (request) => Effect.flatMap(SqlClient.SqlClient, (sql) =>
-    sql.unsafe(updateUserSql, [request.email, request.id])
-  ),
+  execute: (request) =>
+    Effect.flatMap(SqlClient.SqlClient, (sql) =>
+      sql.unsafe(updateUserSql, [request.email, request.id]),
+    ),
 });
 
 /**
@@ -146,7 +145,6 @@ export const deleteUserSql = String.raw`DELETE FROM users
 WHERE id = $1::uuid`;
 export const deleteUser = SqlSchema.void({
   Request: DeleteUserParamsSchema,
-  execute: (request) => Effect.flatMap(SqlClient.SqlClient, (sql) =>
-    sql.unsafe(deleteUserSql, [request.id])
-  ),
+  execute: (request) =>
+    Effect.flatMap(SqlClient.SqlClient, (sql) => sql.unsafe(deleteUserSql, [request.id])),
 });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "effql-workspace",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": true,
   "description": "sqlc-style TypeScript code generation for Effect SQL using Postgres introspection",
   "keywords": [
@@ -9,7 +9,6 @@
     "effect-ts",
     "postgres",
     "sql",
-    "sqlc",
     "typescript"
   ],
   "homepage": "https://github.com/gloomweaver/effql#readme",

packages/cli/README.md

@@ -0,0 +1,55 @@
+# @effql/cli
+
+[![npm: @effql/cli](https://img.shields.io/npm/v/%40effql%2Fcli?label=%40effql%2Fcli)](https://www.npmjs.com/package/@effql/cli)
+
+CLI package for `effql`.
+
+It publishes the `effql` command.
+
+## Install
+
+```bash
+npm install -D @effql/cli @effql/core
+```
+
+```bash
+pnpm add -D @effql/cli @effql/core
+```
+
+## Usage
+
+Bootstrap a project:
+
+```bash
+npx @effql/cli init
+npx @effql/cli init --config ./effql.config.ts
+```
+
+This writes:
+
+- `effql.config.ts`
+- `sql/queries.sql`
+- `package.json` if missing
+
+Installed locally:
+
+```bash
+npx effql init
+npx effql generate
+npx effql generate --config ./effql.config.ts
+```
+
+One-off usage:
+
+```bash
+npx @effql/cli generate
+pnpm dlx @effql/cli generate
+```
+
+## Help
+
+```bash
+effql --help
+```
+
+See the main repo README for config details and the end-to-end example.