datasqwers 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# Datasqwers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Responsive dashboards in the browser that refresh immediately as you select filters. Click any
+value in a filter box and every chart, KPI, table and filter box updates almost instantly. Values
+show as **indigo** (selected), **plain** (possible), **light indigo** (alternatives) or **faded**
+(excluded), so you always see what your selection includes and what it rules out.
+
+You don't build dashboards by dragging things around. You tell Claude what you want, and Claude
+writes the dashboard for you.
+
+Your tables are threaded together on their shared fields, like pieces on a skewer: pull on one
+and the rest move with it.
+
+## What it needs: four ingredients
+
+1. **Connection**: how to reach your data (a database, or CSV/Excel/Parquet files)
+2. **Queries**: which tables or views to pull (ideally clean, analytics-ready views)
+3. **Links**: which fields connect those tables (e.g. `CustomerID`)
+4. **UI**: what you want to see: filters, KPIs, charts, tables
+
+You only provide #1. Then tell Claude what you want to see, and Claude fills in #2–#4.
+
+## What you need on your computer
+
+- A **Mac or Windows** computer (Linux works too).
+- **Node.js** 20 or later (free; step 1 below).
+- **Claude Code** (step 2 below). It needs a paid Claude plan (Pro, Max, Team or Enterprise) or an
+  Anthropic API account.
+- **Your data**, when you're ready for it. You can start with the built-in example and no data at
+  all.
+
+## 1. Install Node.js (once)
+
+Download the **LTS** installer from [nodejs.org](https://nodejs.org/en/download) and run it.
+Or, if you use a package manager:
+
+| Mac (Homebrew) | Windows (PowerShell or Command Prompt) |
+|---|---|
+| `brew install node` | `winget install OpenJS.NodeJS.LTS` |
+
+Then open a **new** terminal window and check that it worked:
+
+```bash
+node --version
+```
+
+It should print `v20` or higher. On a Mac the terminal is the **Terminal** app; on Windows, use
+**PowerShell** or **Command Prompt** from the Start menu.
+
+## 2. Install Claude Code (once)
+
+Either install the **Claude desktop app** ([download](https://claude.ai/download)) and use its
+**Code** tab, or install Claude Code in the terminal:
+
+**Mac:**
+
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://claude.ai/install.ps1 | iex
+```
+
+Then run `claude` once and sign in. More options and help:
+[Claude Code setup](https://code.claude.com/docs/en/setup).
+
+## 3. Make a folder for your dashboards
+
+Any empty folder works. In the desktop app, create it in Finder or File Explorer and choose it
+when you start a session. In the terminal:
+
+**Mac:**
+
+```bash
+mkdir ~/dashboards && cd ~/dashboards && claude
+```
+
+**Windows (PowerShell):**
+
+```powershell
+mkdir $HOME\dashboards; cd $HOME\dashboards; claude
+```
+
+## 4. Tell Claude to set it up
+
+Paste this to Claude:
+
+> Set up Datasqwers in this folder: run `npx datasqwers@latest init --example`, then read
+> DATASQWERS.md and follow it from now on. Pull the example data, start the dashboard server in
+> the background, and give me the link.
+
+Claude creates the project, builds a sample shop dashboard from made-up data, and gives you a link
+such as http://localhost:5173. Open it and click around: select a region, a year or a customer,
+and watch everything update.
+
+From now on, Claude reads `DATASQWERS.md` whenever you work in this folder, so it knows how to
+build and change your dashboards.
+
+## 5. Use your own data
+
+**From a database.** Connection details go in a file called `.env` in the folder, and nowhere
+else. Don't paste passwords into the chat. Open the file:
+
+| Mac | Windows |
+|---|---|
+| `open -e .env` | `notepad .env` |
+
+and add one line, giving the connection a name you'll use with Claude:
+
+```
+SALES_DB=postgresql://user:password@host:5432/dbname
+```
+
+MySQL (`mysql://user:password@host:3306/db`), SQLite (`sqlite:C:/path/to/file.db` or
+`sqlite:/Users/me/file.db`) and DuckDB (`duckdb:path`) work too. Use forward slashes in paths,
+even on Windows.
+
+**From files.** Put your CSV, Excel or Parquet files in the folder (or tell Claude where they
+are). No `.env` entry is needed.
+
+**Then ask for what you want to see**, for example:
+
+> Build a sales dashboard from SALES_DB. Use the views in the `analytics` schema. I want filters
+> for year, region, product category and customer; KPIs for revenue, margin and order count;
+> revenue by month vs budget; top products; and a top-customers table.
+
+or
+
+> Build a dashboard from orders.csv and customers.xlsx. They share the customer ID. Show sales
+> by month and by region, and the top 20 customers.
+
+Claude looks at your data, writes the data model and the dashboard, pulls the data, and checks
+that everything links up correctly. To change anything ("move the region filter to the top",
+"add a margin % column", "split revenue by channel"), just ask. The page updates as soon as the
+files change.
+
+## Everyday use
+
+Claude runs these for you, but you can also run them yourself in the folder:
+
+```bash
+npx datasqwers dev
+```
+
+This opens the dashboards at http://localhost:5173 (or the next free port); add `?d=<name>` to the
+address to pick one. Stop it with Ctrl+C.
+
+```bash
+npx datasqwers refresh sales
+```
+
+This pulls fresh data for the `sales` model, and the open page reloads by itself. Your database is
+only queried during a refresh; all clicking and filtering happens in the browser.
+
+## Troubleshooting
+
+- **`node` or `npx` is "not recognized" or "not found".** Open a new terminal window after
+  installing Node.js. On Windows, if it still fails, restart the computer.
+- **Windows: "running scripts is disabled on this system".** PowerShell is blocking `npx`. Type
+  `npx.cmd` instead of `npx` (e.g. `npx.cmd datasqwers dev`), or use Command Prompt.
+- **Mac: I can't see `.env` in Finder.** Files starting with a dot are hidden. Press
+  Cmd+Shift+. to show them, or open it with `open -e .env` as above.
+- **The first refresh is slow, or fails without internet.** The first time it reads from
+  Postgres, MySQL, SQLite or Excel, Datasqwers downloads a small driver. After that it's cached.
+- **A card on the dashboard shows an error.** Ask Claude to fix it: the message tells it what's
+  wrong. The **Data model** tab shows how your tables link and any warnings.
+
+## Good to know
+
+- **Selecting values.** Click selects one value; ctrl/⌘-click adds more. Drag down a filter
+  box or across a chart to select a range. Back, Forward, History (jump to any earlier
+  selection) and Clear all are at the top right.
+- **Size.** It runs comfortably up to a few million rows in the browser. For more, Claude can
+  summarise the data in the queries (e.g. daily totals instead of every order line).
+- **Where things live:** `models/` (data models), `dashboards/` (layouts), `.env`
+  (connections), `data/` (pulled data), `DATASQWERS.md` (the guide Claude follows).
+- **Sharing.** `npx datasqwers build` makes a static website in `dist/`. Anyone who can open it
+  can also download the data in it, so don't put it on a public server.
+- **Updating.** Run `npx datasqwers@latest init` again to get the newest guide for Claude.
+
+## Developing Datasqwers itself
+
+Clone this repo and run `npm install`. The repo is also a project folder: `npm run dev` serves
+its `dashboards/` with hot reload of the app code, and `npm run refresh -- <model>` stands in for
+`npx datasqwers refresh`. `npm run build` builds the package (`dist/app` and `dist/cli`); to try
+it as a user would, run `npm pack` and then `npx /path/to/datasqwers-<version>.tgz init` in
+another folder.
+
+To try it on a larger demo database (needs Docker):
+
+```bash
+npm run demo:db
+npm run refresh -- demo
+npm run dev
+```
+
+`demo:db` starts a demo Postgres in Docker (1M sales lines, 20k customers). Remove it later with
+`docker rm -f datasqwers-demo-pg`.

package/bin/datasqwers.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli/datasqwers.js';