@nestica/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Ascuy
+
+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,156 @@
+# nestica-cli
+
+Command-line client for the Nestica REST API (`nestica-api`): full CRUD
+over `profiles`, `accounts`, `contacts`, `transactions` and `yields`,
+plus session management (`login`, `logout`, `whoami`, `set-profile`).
+
+## Install
+
+Published package: `npm install -g @nestica/cli` (zero runtime
+dependencies — everything is bundled into the `nestica` binary).
+
+From this repository:
+
+```sh
+pnpm install
+pnpm --filter @nestica/cli build
+pnpm exec nestica --help
+```
+
+The CLI talks to the deployed API by default
+(`https://api-tjnuhxmzkq-uc.a.run.app/api/v1.0`); point it elsewhere
+with `--base-url` or `NESTICA_BASE_URL`.
+
+## Sessions
+
+State lives in one JSON file with owner-only permissions:
+`${XDG_CONFIG_HOME:-~/.config}/nestica/config.json` (override the whole
+path with `NESTICA_CONFIG`). It stores the connection settings, the
+Firebase tokens and the default profile. Precedence for every setting:
+**flag > environment > session file > default**.
+
+| Setting | Flag | Environment | Default |
+| --- | --- | --- | --- |
+| API base URL | `-H, --base-url` | `NESTICA_BASE_URL` | deployed API |
+| Firebase web API key | `--api-key` | `FIREBASE_API_KEY` | — |
+| Google OAuth client id | `--google-client-id` | `GOOGLE_CLIENT_ID` | — |
+| Google OAuth client secret | `--google-client-secret` | `GOOGLE_CLIENT_SECRET` | — |
+| Auth emulator | — | `FIREBASE_AUTH_EMULATOR_HOST` | inferred from a localhost base URL |
+
+Expired ID tokens refresh automatically before requests; when the
+refresh token itself is rejected the CLI says so and asks for a new
+`login`.
+
+## Commands
+
+```
+nestica login [--email <email>] [--password <pw>] [--google] ...
+nestica logout
+nestica whoami
+nestica set-profile [<id>] [--clear]
+
+nestica <resource> list [--page <n>] [--page-size <n>] [--profile <uuid>]
+nestica <resource> get <id>
+nestica <resource> create [field flags] [--data <json|->]
+nestica <resource> update <id> [field flags] [--data <json|->]
+nestica <resource> delete <id>
+```
+
+`<resource>` is `profiles | accounts | contacts | transactions |
+yields`. Scoped resources send the stored default profile (or an
+explicit `--profile`) as the `profileId` query parameter; `transactions
+list` also takes `--type expense|income`.
+
+Global flags: `-H/--base-url`, `--api-key`, `--profile`,
+`-F/--format pretty|json|table` (default `pretty`), `--no-color`
+(or `NO_COLOR`; color is also off when stdout is not a TTY).
+
+### login
+
+- Email/password (prompted when omitted; the password is not echoed):
+  `nestica login --api-key <web-key> --email dev@example.com`
+- Google, in the browser (OAuth + PKCE against a loopback redirect;
+  needs the Firebase project's web OAuth client id):
+  `nestica login --google --google-client-id <id> --api-key <key>`
+
+`logout` deletes the session file.
+
+### set-profile
+
+`nestica set-profile` lists the profiles and asks which one to make the
+default; `nestica set-profile <uuid>` stores a specific one and
+`--clear` removes it. The API would otherwise default to the first
+profile created.
+
+### Field flags
+
+Create/update bodies come from typed flags — identical rules to the
+API, validated locally with `@nestica/models` — plus `--data` (or
+`--json`) to merge a raw JSON body over them (`-` reads stdin):
+
+```sh
+nestica profiles create --name Gary --country CO --timezone America/Bogota \
+  --currency COP --currency USD --default-currency COP
+
+nestica accounts create --name Bancolombia --label bank
+
+nestica transactions create --type expense --amount 42.5 --currency COP \
+  --date 2026-08-22T12:00:00Z --status settled --label groceries \
+  --foreign-amount '{"amount": 10, "currency": "USD"}'
+
+nestica transactions update <id> --amount 50
+```
+
+See `nestica <resource> create --help` for every flag; `--label`,
+`--currency` (profiles) and other list flags are repeatable
+(`--label a --label b`).
+
+### Output
+
+- `--format pretty` (default): colorized, indented JSON.
+- `--format json`: compact single-line JSON for shell pipelines
+  (`nestica accounts list --format json | jq -r '.data[0].id'`).
+- `--format table`: column table for lists, key/value listing for
+  single records; the list summary goes to stderr so stdout stays
+  parseable.
+
+Delete confirmations also go to stderr; with `--format json` deletes
+print nothing at all.
+
+### Exit codes
+
+`0` success · `1` API/runtime errors · `2` usage errors.
+
+## Smoke test against the emulators
+
+```sh
+pnpm --filter nestica-api serve      # functions :5001, firestore :8080, auth :9099
+# create a user once in the Auth UI at http://localhost:4000
+
+export FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
+pnpm exec nestica login \
+  --base-url http://localhost:5001/nestica-finances/us-central1/api/api/v1.0 \
+  --api-key demo --email dev@example.com
+
+pnpm exec nestica profiles create --name Gary --country CO \
+  --timezone America/Bogota --currency COP --default-currency COP
+pnpm exec nestica set-profile
+pnpm exec nestica accounts create --name Bancolombia --label bank
+pnpm exec nestica transactions create --type expense --amount 42.5 \
+  --currency COP --date 2026-08-22T12:00:00Z --status settled --label groceries
+pnpm exec nestica transactions list --type expense --format table
+pnpm exec nestica whoami
+pnpm exec nestica logout
+```
+
+Note: the Google flow always talks to the real Google endpoints — use
+email/password with the emulators.
+
+## Tests
+
+```sh
+pnpm --filter @nestica/cli test
+```
+
+Unit tests only (mocked `fetch`, temporary session files); the
+repository-wide `pnpm test` runs them through Nx.