@noy-db/create 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+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

@@ -0,0 +1,283 @@
+# @noy-db/create
+
+Wizard + CLI tool for [noy-db](https://github.com/vLannaAi/noy-db) — scaffold a fresh Nuxt 4 + Pinia encrypted store, augment an existing Nuxt project, or run operational commands (add user, rotate keys, backup) from the command line.
+
+Two bins ship in this package:
+
+- **`create`** — invoked by `npm create @noy-db`. Fresh-project wizard OR in-place augmenter for an existing Nuxt 4 project, depending on where you run it.
+- **`noy-db`** — ongoing CLI tool. Invoked via `pnpm exec noy-db <cmd>` or `npx noy-db <cmd>` from inside a project. Five subcommands: `add`, `add user`, `verify`, `rotate`, `backup`.
+
+---
+
+## `create @noy-db` — the wizard
+
+The wizard auto-detects whether your current directory is an existing Nuxt 4 project:
+
+- If `nuxt.config.{ts,js,mjs}` **and** a `package.json` listing `nuxt` are both present, the wizard enters **augment mode** (patches the existing config in-place)
+- Otherwise it enters **fresh mode** (creates a new subdirectory with a full Nuxt 4 starter)
+
+### Fresh mode — new project
+
+```bash
+# In an empty directory
+npm  create @noy-db my-app
+pnpm create @noy-db my-app
+yarn create @noy-db my-app
+bun  create @noy-db my-app
+```
+
+The wizard asks at most 3 questions (project name, adapter, include sample data) and writes a complete Nuxt 4 + Pinia + `@noy-db/nuxt` starter into `./my-app/`. Nothing is installed automatically — pick your package manager and run it yourself.
+
+Skip the prompts with `--yes`:
+
+```bash
+npm create @noy-db my-app --yes
+npm create @noy-db my-app --yes --adapter file --no-sample-data
+```
+
+### Augment mode — existing Nuxt 4 project
+
+```bash
+# From inside an existing Nuxt 4 project root
+cd ~/my-existing-app
+npm create @noy-db
+```
+
+The wizard will:
+
+1. **Detect** the existing `nuxt.config.ts` via the detection rule above
+2. **Prompt** for the adapter (`browser` / `file` / `memory`)
+3. **Patch** the config in-memory via [magicast](https://github.com/unjs/magicast):
+   - Add `'@noy-db/nuxt'` to the `modules` array (creating the array if missing)
+   - Add `noydb: { adapter, pinia: true, devtools: true }` (only if not already present)
+4. **Show** a colored unified diff of the proposed changes
+5. **Ask** for confirmation (`y/n`) — your config is only written if you confirm
+6. **Print** the `pnpm add …` command for the packages the patched config now depends on
+
+#### Safe behaviors
+
+- **Idempotent**: re-running on an already-augmented project is a no-op. You'll see `Nothing to do — already configured`.
+- **Preserves custom config**: a pre-existing `noydb:` key in your config is left untouched. The wizard only fills in what's missing.
+- **Preserves unrelated keys, comments, and formatting**: magicast walks a real Babel AST, not a regex.
+- **Unsupported shapes are rejected cleanly**: if your config uses an opaque export (`export default someVar`) or a non-array `modules` field, the wizard bails with a clear error message telling you to edit manually.
+
+#### Dry run
+
+Preview the diff without writing anything:
+
+```bash
+npm create @noy-db --dry-run
+```
+
+Prints the unified diff and exits. Useful in CI, code review, and "what would this do to my config?" exploration.
+
+#### Force fresh mode inside an existing project
+
+If you're inside a Nuxt workspace but want to create a **new** sub-project rather than augment the root, pass `--force-fresh`:
+
+```bash
+cd ~/my-monorepo-with-nuxt
+npm create @noy-db my-sub-app --force-fresh
+```
+
+### All flags
+
+| Flag | Effect |
+|---|---|
+| `<project-name>` (positional) | Target directory name (fresh mode only) |
+| `-y`, `--yes` | Skip every prompt; use defaults |
+| `--adapter <name>` | Pre-select adapter: `browser` (default) / `file` / `memory` |
+| `--no-sample-data` | (fresh mode) Skip the seed invoice records |
+| `--dry-run` | (augment mode) Show the diff without writing |
+| `--force-fresh` | Force fresh-project mode even in an existing Nuxt dir |
+| `--lang <code>` | UI language: `en` (default) / `th`. Auto-detected from `LC_ALL` / `LANG` when omitted |
+| `-h`, `--help` | Show usage and exit |
+
+#### Languages
+
+The wizard's prompts and notes are available in **English** (default) and **Thai** (`th`). Pick a language explicitly with `--lang`:
+
+```bash
+npm create @noy-db my-app --lang th
+```
+
+When `--lang` is omitted, the wizard reads the standard POSIX locale env vars (`LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`) and auto-selects Thai when they point to a Thai locale, e.g.:
+
+```bash
+LANG=th_TH.UTF-8 npm create @noy-db my-app
+```
+
+Validation errors and stack traces stay in English regardless of language so bug reports look the same in any locale.
+
+---
+
+## `noy-db` — the CLI tool
+
+The `noy-db` bin ships inside the same `@noy-db/create` package. Install it as a dev dependency and it's available via `pnpm exec` / `npx`:
+
+```bash
+pnpm add -D @noy-db/create
+pnpm exec noy-db <command>
+```
+
+### Commands at a glance
+
+| Command | Purpose |
+|---|---|
+| `noy-db add <collection>` | Scaffold a new Pinia store + Vue page for a collection |
+| `noy-db add user <id> <role>` | Grant a new user access to a compartment |
+| `noy-db verify` | In-memory crypto round-trip integrity check |
+| `noy-db rotate` | Rotate DEKs for one or more collections |
+| `noy-db backup <target>` | Dump a compartment to an encrypted file |
+
+All commands that touch real compartments use the **file adapter** and require these flags:
+
+- `--dir <path>` — the data directory. Defaults to `./data`.
+- `--compartment <name>` — the compartment (tenant) name. Required.
+- `--user <id>` — your own user id in the compartment. Required.
+
+You'll be prompted for your passphrase at runtime. Passphrases are never echoed, never logged, never written to disk, and cleared from process memory when the command exits.
+
+### `noy-db add <collection>`
+
+Scaffolds two new files in your project:
+
+- `app/stores/<name>.ts` — a `defineNoydbStore<Name>()` call with a placeholder interface
+- `app/pages/<name>.vue` — a minimal CRUD page that lists, adds, and deletes records
+
+```bash
+pnpm exec noy-db add clients
+```
+
+Refuses to overwrite existing files — if either target already exists, the command exits non-zero without touching anything. There's no `--force` flag; delete the old files manually if you want to regenerate.
+
+### `noy-db add user <userId> <role> [options]`
+
+Grants a new user access to a compartment. Two passphrase prompts: yours (caller), then the new user's (with confirmation).
+
+```bash
+pnpm exec noy-db add user accountant-ann operator \
+  --dir ./data \
+  --compartment demo-co \
+  --user owner-alice \
+  --collections invoices:rw,clients:ro
+```
+
+Roles:
+
+| Role | Permissions | Requires `--collections`? |
+|---|---|:---:|
+| `owner` | All collections, all operations | No |
+| `admin` | All collections, all operations (except grant owner) | No |
+| `viewer` | All collections, read-only | No |
+| `operator` | Per-collection `rw` or `ro` explicitly | **Yes** |
+| `client` | Per-collection `ro` explicitly | **Yes** |
+
+For `operator` and `client`, the `--collections` flag is required. Format: `name1:rw,name2:ro,name3:rw`.
+
+### `noy-db verify`
+
+Runs an end-to-end crypto round-trip against an in-memory adapter. No real data is touched; the command creates a throwaway compartment, writes a record, reads it back, and verifies it decrypts correctly. Useful as a sanity check that `@noy-db/core`, `@noy-db/memory`, and your local Node version all agree on Web Crypto.
+
+```bash
+pnpm exec noy-db verify
+# ✔ noy-db integrity check passed (126ms)
+```
+
+Exits non-zero if anything diverges.
+
+### `noy-db rotate [options]`
+
+Rotate the DEKs for one or more collections in a compartment. Generates fresh keys, re-encrypts every record with the new keys, and re-wraps the new keys into every user's keyring. Nobody is revoked — everyone keeps their current permissions with fresh key material.
+
+```bash
+# Rotate every collection in the compartment
+pnpm exec noy-db rotate --dir ./data --compartment demo-co --user owner-alice
+
+# Rotate specific collections only
+pnpm exec noy-db rotate --dir ./data --compartment demo-co --user owner-alice \
+  --collections invoices,clients
+```
+
+Use cases:
+
+- **Suspected key leak**: an operator lost a laptop, a developer accidentally pasted a passphrase into a Slack channel, a USB stick went missing. Rotating is cheap insurance.
+- **Scheduled rotation**: some compliance regimes require periodic key rotation regardless of exposure. This command makes rotation scriptable from cron or a CI job.
+
+Different from `noydb.revoke({ rotateKeys: true })` in that it doesn't kick anyone out — it's the "just rotate" path.
+
+### `noy-db backup <target> [options]`
+
+Dump a compartment to a local file. The dump is a **verifiable backup**: it includes the chain head and the full `_ledger` / `_ledger_deltas` snapshots, so `compartment.load()` on the receiving side will reject any tampering between dump and restore.
+
+```bash
+pnpm exec noy-db backup ./backups/demo-2026-04-07.json \
+  --dir ./data --compartment demo-co --user owner-alice
+```
+
+Target paths:
+
+- **Plain filesystem path** — `./backups/demo.json` or `/absolute/path.json`
+- **`file://` URI** — `file:///absolute/path.json` or `file://./relative.json`
+
+Parent directories are created on demand, so `./backups/2026/04/demo.json` works even if `./backups/2026/04/` doesn't exist yet.
+
+Unsupported schemes (`s3://`, `https://`, etc.) are rejected **before** the passphrase prompt so a typo doesn't waste a passphrase entry.
+
+### `noy-db help`
+
+Prints the full usage message for all subcommands.
+
+---
+
+## Security invariants
+
+Every command that touches real compartments follows these rules:
+
+1. **Passphrase via `@clack/prompts` `password()`** — never echoes to the terminal, never logged.
+2. **Passphrase never leaves the local closure** — no file writes, no error messages, no telemetry.
+3. **Ctrl-C at the prompt aborts before any I/O happens** — cancelling doesn't leave the system in a half-mutated state.
+4. **`finally { db.close() }`** — KEK is cleared from process memory on exit, success or failure.
+5. **Unsupported backup schemes are rejected before the prompt** — a typo doesn't waste a passphrase entry.
+
+---
+
+## What's in the fresh-project template
+
+```
+my-app/
+├── nuxt.config.ts          ← @noy-db/nuxt wired up with your chosen adapter
+├── package.json            ← @noy-db/* deps at ^0.5.0
+├── tsconfig.json
+├── README.md
+├── .gitignore
+└── app/
+    ├── app.vue
+    ├── stores/
+    │   └── invoices.ts     ← defineNoydbStore<Invoice>
+    └── pages/
+        ├── index.vue
+        └── invoices.vue    ← CRUD page with reactive query DSL
+```
+
+Everything stored is encrypted with AES-256-GCM before it touches the adapter. The adapter only ever sees ciphertext.
+
+---
+
+## Deferred to a future release
+
+These are explicit non-goals:
+
+- **Thai i18n** of the wizard prompts ([#36](https://github.com/vLannaAi/noy-db/issues/36))
+- **Non-Nuxt templates** — no Vite/Vue standalone, no Electron, no vanilla ([#39](https://github.com/vLannaAi/noy-db/issues/39))
+- **`noy-db seed`** — needs a design decision about how seed scripts authenticate
+- **S3 backup targets** — would bundle `@aws-sdk` into this package and break the zero-runtime-deps story; lives in a companion package instead
+- **`noy-db restore <file>`** — paired with the existing `compartment.load()` + integrity check; deferred so it can be designed alongside future identity/session work
+
+Open an issue if you need one of these sooner.
+
+---
+
+## License
+
+MIT

package/dist/bin/create.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node