tracksiy 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lutfios
+
+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,184 @@
-# Temporary Holding Version
+# tracksiy
 
-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.
+The command line and MCP server for [Tracksiy](https://tracksiy.com): error tracking, uptime monitoring, alerting, releases and source maps, for every app of an organization, from one token.
+
+It is built for **agents first**. Everything a person would click in a dashboard is one command with a stable JSON answer. That covers integrating a new app, finding what broke, proving someone gets alerted, and uploading source maps from a deploy.
+
+```sh
+npx tracksiy --help
+```
+
+No install, no runtime dependencies, Node.js 20 or newer.
+
+## Start
+
+```sh
+export TRACKSIY_TOKEN=...      # Dashboard > Profile > Auth tokens, or `tracksiy tokens create`
+npx tracksiy auth status       # who am I, which organizations and projects
+npx tracksiy overview          # the whole fleet: new issues, trends, silent apps, monitors down
+npx tracksiy issues list --since 24h
+npx tracksiy issues view 4812  # stack frames, latest event, tags: enough to fix it
+```
+
+Integrating an app, from inside its directory:
+
+```sh
+npx tracksiy init --write-env          # detect the stack, create the project and keys, write .tracksiy.json
+# install the SDK as the printed guide says, deploy, trigger one error, then:
+npx tracksiy projects verify --wait 120
+```
+
+## For agents
+
+- **JSON whenever stdout is not a terminal.** One line: `{"ok":true,"data":...}`, or `{"ok":false,"error":{"code","message","hint"}}`. The `hint` says what to do next.
+- **Stable exit codes:**
+
+  | Code | Meaning |
+  | --- | --- |
+  | 0 | ok |
+  | 2 | usage error, nothing sent |
+  | 3 | auth |
+  | 4 | not found |
+  | 5 | rejected as invalid |
+  | 6 | rate limited |
+  | 7 | network |
+  | 8 | server error |
+  | 9 | server older than the CLI |
+  | 10 | the check ran and did not pass (`health`, `projects verify`, `alerts test`) |
+
+- **`--select a,b.c`** keeps only the fields you need, so results stay small. Dot paths reach into lists: `--select issues.id,issues.title`.
+- **`tracksiy describe`** prints every command, flag, exit code and error code as JSON. `tracksiy <command> --help` is the same thing, readable.
+- **Never prompts.** Writes are idempotent declarations, so re-running them is safe. Destructive commands need `--yes`. Bulk changes are dry runs unless `--apply`.
+- **Typos are caught before anything is sent**, with a suggestion: `Unknown flag --staus. Did you mean --status?`
+- **Organization and project resolve themselves**, in this order: `--org`/`--project`, then `TRACKSIY_ORG`/`TRACKSIY_PROJECT`, then `.tracksiy.json` (searched upward from the working directory), then the only one the token can see.
+
+## MCP server
+
+`tracksiy mcp` serves every command as an MCP tool over stdio, with the same validation, the same errors and a `select` argument on every tool.
+
+Claude Code:
+
+```sh
+claude mcp add tracksiy -e TRACKSIY_TOKEN=<token> -- npx -y tracksiy mcp
+```
+
+Claude Desktop, Cursor, Windsurf and most other clients:
+
+```json
+{
+  "mcpServers": {
+    "tracksiy": {
+      "command": "npx",
+      "args": ["-y", "tracksiy", "mcp"],
+      "env": { "TRACKSIY_TOKEN": "<token>", "TRACKSIY_ORG": "<org>" }
+    }
+  }
+}
+```
+
+Tool names are the command path joined with underscores: `issues_list`, `alerts_set`, `sourcemaps_upload`. Read-only, destructive and idempotent tools are annotated as such.
+
+## In CI
+
+Upload source maps after the build and declare the release from the deploy step. A token with only `project:releases` on one project is enough:
+
+```sh
+npx tracksiy sourcemaps upload dist --inject --project shop
+npx tracksiy releases declare "shop@$GIT_SHA" --ref "$GIT_SHA" --released --project shop
+```
+
+`--inject` stamps each built file and its map with a debug ID, so errors map to the exact build no matter what URL the file was served from. Only chunks the server does not already have are sent.
+
+Android (ProGuard / R8):
+
+```sh
+npx tracksiy proguard upload app/build/outputs/mapping/release/mapping.txt --uuid "$MAPPING_UUID" --project shop-android
+```
+
+## Talking to the Tracksiy team
+
+If Tracksiy itself gets in your agent's way, open a ticket. That covers a bug, a missing capability, an error it cannot interpret, or being blocked. Tickets go through [PeerPacket](https://peerpacket.com) (the `pp` CLI), in the `tracksiy-support` channel, for `tracksiy-agent`, who answers on the ticket and closes it:
+
+```sh
+npm install -g peerpacket
+pp join tracksiy-support
+pp ticket new tracksiy-support "sourcemaps upload: 400 on a map with ?v=" --to tracksiy-agent --label bug -f report.md
+pp tickets tracksiy-support          # answers waiting for you
+```
+
+Labels: `bug`, `feature`, `question`, `blocker`. `npx tracksiy support` prints the same, as JSON for an agent.
+
+## Commands
+
+<!-- commands:start -->
+| Command | What it does | Effect | MCP tool |
+| --- | --- | --- | --- |
+| `init` | Integrate the app in this directory, without a browser: detect the stack, create the project and its keys, write .tracksiy.json, and print the exact next steps. | write | `init` |
+| `auth login` | Check a token against the server and save it for this server (file mode 0600). | write | - |
+| `auth status` | Which server, which token (and where each came from), which organizations and defaults are in effect. | read | `auth_status` |
+| `auth logout` | Forget the saved token for this server. Does not revoke it (use `tokens delete`). | write | - |
+| `orgs list` | Organizations this token can see, each with the projects it may reach. | read | `orgs_list` |
+| `projects list` | Projects of the organization that this token may reach. | read | `projects_list` |
+| `overview` | The whole fleet in one call: per-project issues, volume trend, silence, monitors and alert coverage. | read | `overview` |
+| `changes` | What changed since a point in time: new issues, monitors going down or up, new releases. | read | `changes` |
+| `health` | Can the platform itself be believed right now? Exit code 10 when any check fails. | read | `health` |
+| `monitors list` | Every monitor of the organization with its state, including monitors no project owns. | read | `monitors_list` |
+| `monitors declare` | Declare monitors for a project up front, idempotently: heartbeats for jobs, HTTP checks, TLS, ingest silence. | write | `monitors_declare` |
+| `monitors delete <slug>` | Remove one of a project's monitors by the slug it was declared with. | **destructive** | `monitors_delete` |
+| `performance` | Is this project slow, and did it get slower? Transactions compared with the previous window, plus uptime. | read | `performance` |
+| `issues list` | Recent issues of a project, newest activity first, with the frames that matter inlined. | read | `issues_list` |
+| `issues view <id>` | One issue in enough depth to act on: latest event, stack frames, tags, recent volume. | read | `issues_view` |
+| `issues resolve <ids...>` | Mark issues resolved. A new event on a resolved issue reopens it as a regression. | write | `issues_resolve` |
+| `issues ignore <ids...>` | Mark issues ignored: they stop alerting until unignored. | write | `issues_ignore` |
+| `issues unresolve <ids...>` | Reopen issues. | write | `issues_unresolve` |
+| `issues bulk-status` | Change the status of every issue matching a filter. Dry run unless --apply. | write | `issues_bulk_status` |
+| `projects create <name>` | Everything a new app needs in one idempotent call: the project, an ingest key per surface, an upload token, and the next steps. | write | `projects_create` |
+| `projects verify` | Did the integration actually work? Checks events, releases, environments, source maps, privacy and alerting. Exit 10 if not. | read | `projects_verify` |
+| `onboarding` | What to know before integrating an app. No token needed. | read | `onboarding` |
+| `alerts get` | Who is told when this project breaks, and whether that can actually happen. | read | `alerts_get` |
+| `alerts set` | Declare the project's alerting idempotently. Then prove it with `alerts test`. | write | `alerts_set` |
+| `alerts test` | Send a test message through every recipient and report each delivery. Exit code 10 if any failed. | write | `alerts_test` |
+| `alerts coverage` | For the whole organization: which projects can alert, which cannot, and through what. | read | `alerts_coverage` |
+| `alerts defaults` | Apply one alerting declaration to many projects at once (by default only where none exists). | write | `alerts_defaults` |
+| `alerts settings` | When digest-mode recipients are told, and whether the last digests went out. | read | `alerts_settings` |
+| `alerts settings set` | Declare the digest hours and timezone. | write | `alerts_settings_set` |
+| `keys list` | Every ingest key of the project: its surface, whether ingest accepts it, its rate limit and volume. | read | `keys_list` |
+| `keys set <name>` | Declare one ingest key's state: active or not, and its rate limit. | write | `keys_set` |
+| `keys rotate <name>` | Replace an ingest key with a new one of the same name and limit; the old one stops being accepted. | **destructive** | `keys_rotate` |
+| `releases list` | What did the last deploys break? Recent releases with their events, issues and the issues they introduced. | read | `releases_list` |
+| `releases health` | Is the app crashing for its users, and did the last release make it worse? Crash-free sessions and users per release. | read | `releases_health` |
+| `releases declare <version>` | Create or update a release idempotently: its commit, URL, and when it was released. Run it from the deploy. | write | `releases_declare` |
+| `sourcemaps inject <paths...>` | Stamp built JavaScript and its source maps with a debug ID, so errors map to the exact build. Run after the build, before deploying. | write | `sourcemaps_inject` |
+| `sourcemaps upload <paths...>` | Upload built JavaScript and source maps so stack traces show original files and lines. Only missing bytes are sent. | write | `sourcemaps_upload` |
+| `proguard upload <mapping>` | Upload an Android ProGuard/R8 mapping so obfuscated stack traces are readable. | write | `proguard_upload` |
+| `artifacts list` | What is actually stored for a project: source files, source maps and ProGuard mappings. Use it to prove an upload landed. | read | `artifacts_list` |
+| `tokens list` | Your tokens, newest first, without their values. | read | `tokens_list` |
+| `tokens self` | Describe the token making this call: scopes, projects, expiry. | read | `tokens_self` |
+| `tokens create` | Mint a token for the same user, never broader than the one making the call. | write | `tokens_create` |
+| `tokens update <id>` | Change a token's label, scopes, projects or lifetime (never broader than the caller). | write | `tokens_update` |
+| `tokens delete <id>` | Revoke a token immediately. | **destructive** | `tokens_delete` |
+| `tokens rotate` | Replace the token making this call; the old one keeps working for a grace period. | **destructive** | `tokens_rotate` |
+| `support` | How to tell the Tracksiy team what got in your way: a bug, a missing capability, an error you cannot interpret, or a blocker. | read | `support` |
+| `api <method> <path>` | Call any endpoint directly, for what no command covers yet. Paths are relative to /api/agent/v1/ unless they start with /. | write | `api` |
+| `describe [command...]` | Machine-readable description of every command, flag, exit code and error code. Start here if you are an agent. | read | - |
+| `mcp` | Run as an MCP server on stdio: every command becomes a tool for Claude, Cursor or any MCP client. | read | - |
+<!-- commands:end -->
+
+## Configuration
+
+| Variable | Meaning |
+| --- | --- |
+| `TRACKSIY_TOKEN` | API token. Prefer it over `--token`, which shows up in process lists. |
+| `TRACKSIY_URL` | Server root, for self-hosted installs. Default `https://tracksiy.com`. |
+| `TRACKSIY_ORG`, `TRACKSIY_PROJECT` | Defaults. `TRACKSIY_PROJECT` may be `org/project`. |
+| `TRACKSIY_FORMAT` | `json` or `text`. |
+| `TRACKSIY_TIMEOUT` | Seconds per request, default 30. |
+| `TRACKSIY_CONFIG` | Where `auth login` saves tokens. Default `~/.config/tracksiy/config.json`, mode 0600. |
+
+Saved tokens are kept per server, so a token is never sent to a different `--url`. The CLI also refuses to send a token over plain HTTP to anything but a loopback address.
+
+`.tracksiy.json`, written by `tracksiy init`, holds `{"org": "...", "project": "..."}` and never a secret. Commit it.
+
+## License
+
+MIT