@trillioncore/cli 1.0.0-next.12 → 1.0.0-next.14

package/README.md

@@ -36,7 +36,7 @@ npm exec --yes --package=@trillioncore/cli@next -- tc logout
 
 Browser sign-in lets you choose one or more organizations and explicitly select enabled accounts within each. Membership alone does not authorize a CLI connection; current organization and account permissions still apply. For a brand-new account, use `tc signup`; the browser asks for an organization name and continues without a rerun. No provider reconnection is required just to authorize the CLI.
 
-Prefer `npm exec` during evaluation. `npm install -g @trillioncore/cli@next` replaces your local `tc` executable, even though publishing `next` does not change the npm `latest` tag.
+Prefer `npm exec` during evaluation. `npm install -g @trillioncore/cli` replaces your local `tc` executable.
 
 ## Commands
 
@@ -115,7 +115,7 @@ Discovery follows provider → verified stored identity → declared resources.
 
 Contributors must extend `INTEGRATION_PROVIDER_DEFINITIONS` in `packages/types/src/integrations.ts` for each provider. Its exhaustive typed declaration drives API identity/model discovery and CLI captions. Native models are declared even when empty; PostgreSQL retains only existing stored row projections plus approved relational manifests. Unknown providers and undeclared model kinds have no generic fallback. Index does not fetch providers to fill missing identity.
 
-A connection is one authorized provider account, a resource describes an available representation, and an operation describes how to access it. Analytical SQL and non-analytical search/get are capabilities, not mutually exclusive integration categories. Native API connectors and optional Airbyte ingestion are internal mechanisms; Airbyte is not a search provider filter. Multiple adapters may eventually support one connection, with separate credentials or action grants where needed. GitHub uses the configured self-hosted Airbyte path; existing providers retain their current ingestion paths. No provider business actions or cross-source SQL are implemented. PostgreSQL discovery distinguishes approved live SQL from synchronized datasets; a synchronized schema is not proof that its query transport is configured.
+A connection is one authorized provider account, a resource describes an available representation, and an operation describes how to access it. Analytical SQL and non-analytical search/get are capabilities, not mutually exclusive integration categories. Native API connectors and synced ingestion are internal mechanisms, not search provider filters. Multiple adapters may eventually support one connection, with separate credentials or action grants where needed. GitHub uses the configured self-hosted sync service; existing providers retain their current ingestion paths. No provider business actions or cross-source SQL are implemented. PostgreSQL discovery distinguishes approved live SQL from synchronized datasets; a synchronized schema is not proof that its query transport is configured.
 
 ### GitHub pull requests
 
@@ -128,11 +128,11 @@ tc get --ref '<returned-record-ref>' --json
 tc sql '<connection-id>' 'SELECT repository, count(*) FROM pull_requests GROUP BY repository' --target synced --json
 ```
 
-GitHub SQL and search/get read the same published dataset revision, not mutable Airbyte tables. Synced SQL is bounded to 200 returned rows and response-size limits. The SQL `creator` column corresponds to the PR author; search/get attributes use `author`. Reads recheck current account/token authorization. Repository selection shrink hides the previous publication until synchronization completes. This first slice covers pull requests only; issues/comments/reviews are not yet exposed and upstream deletion completeness is unverified.
+GitHub SQL and search/get read the same published dataset revision, not mutable synced tables. Synced SQL is bounded to 200 returned rows and response-size limits. The SQL `creator` column corresponds to the PR author; search/get attributes use `author`. Reads recheck current account/token authorization. Repository selection shrink hides the previous publication until synchronization completes. This first slice covers pull requests only; issues/comments/reviews are not yet exposed and upstream deletion completeness is unverified.
 
-Interrupted setup remains a saved, disabled connection. Use Manage to reconnect or remove it rather than adding a duplicate. Creation intents and exact remote names allow cleanup after lost responses. If an ambiguous creation cannot yet be found in Airbyte, recovery fails closed and retains the intent; an operator must reconcile the remote outcome before it can be cleared. Superseded and abandoned dataset revisions are durably tracked for bounded cleanup on the next sync, reconnect or removal.
+Interrupted setup remains a saved, disabled connection. Use Manage to reconnect or remove it rather than adding a duplicate. Creation intents and exact remote names allow cleanup after lost responses. If an ambiguous creation cannot yet be found in the sync service, recovery fails closed and retains the intent; an operator must reconcile the remote outcome before it can be cleared. Superseded and abandoned dataset revisions are durably tracked for bounded cleanup on the next sync, reconnect or removal.
 
-Self-hosted Airbyte and an operator-vetted PostgreSQL provisioning endpoint must be configured before connections are available. The destination can be Trillioncore's existing Neon database: GitHub uses dedicated schemas and per-revision reader roles, not another warehouse database. Use Neon's direct endpoint for the replication/provisioning URL, not its `-pooler` endpoint: lifecycle synchronization uses session advisory locks, which transaction pooling cannot preserve. This is another connection endpoint for the same database; the application's existing pooled URL stays unchanged. Its internal schema-isolation policy permits ordinary database PUBLIC CONNECT/TEMPORARY defaults, but rejects permanent CREATE rights, PUBLIC dataset grants (including column grants), unrelated data access and non-scalar/view-backed snapshots. Queries use fresh read-only sessions with pinned function lookup and bounded validated SQL. Existing strict database-isolation callers retain their original policy. The application does not change global PUBLIC privileges to make provisioning work. Actual runtime versions, destination naming, licensing and live acceptance remain deployment checks; synthetic fixtures do not establish compatibility with every Airbyte version.
+The self-hosted sync service and an operator-vetted PostgreSQL provisioning endpoint must be configured before connections are available. The destination can be Trillioncore's existing Neon database: GitHub uses dedicated schemas and per-revision reader roles, not another warehouse database. Use Neon's direct endpoint for the replication/provisioning URL, not its `-pooler` endpoint: lifecycle synchronization uses session advisory locks, which transaction pooling cannot preserve. This is another connection endpoint for the same database; the application's existing pooled URL stays unchanged. Its internal schema-isolation policy permits ordinary database PUBLIC CONNECT/TEMPORARY defaults, but rejects permanent CREATE rights, PUBLIC dataset grants (including column grants), unrelated data access and non-scalar/view-backed snapshots. Queries use fresh read-only sessions with pinned function lookup and bounded validated SQL. Existing strict database-isolation callers retain their original policy. The application does not change global PUBLIC privileges to make provisioning work. Actual runtime versions, destination naming, licensing and live acceptance remain deployment checks; synthetic fixtures do not establish compatibility with every sync service version.
 
 ## Sessions and troubleshooting
 
@@ -148,6 +148,22 @@ One profile is active at a time. A new successful login replaces it and attempts
 - Advanced/manual use: `TRILLIONCORE_TOKEN` and `TRILLIONCORE_ORG_ID` must be supplied together and override the saved session. Remove both to use browser login. API overrides prefer `TRILLIONCORE_CLI_API_URL`, then `TRILLIONCORE_API_URL`; a mismatch with a saved session is refused, not silently redirected. Application API configuration is never rewritten.
 - `TRILLIONCORE_CONFIG_DIR` selects a private CLI-only profile directory (also useful for isolated testing). Legacy v0 configuration is not migrated.
 
+### Error reporting
+
+The CLI sends error reports to Trillioncore’s dedicated `v1-cli` Sentry project by default. You don’t need a Sentry account or any configuration. Its public reporting address is included in the downloaded CLI; it does not grant access to Sentry.
+
+To turn reporting off, set `DO_NOT_TRACK=1` in your environment. For a single command:
+
+```sh
+DO_NOT_TRACK=1 tc index
+```
+
+Reporting is also off when `NODE_ENV=test`. For diagnostics, `SENTRY_DSN` can override the reporting destination; an unset or empty value uses the built-in destination. The CLI does not load a `.env` file.
+
+Reports include the CLI version, the `v1-cli` service tag and technical stack coordinates. `SENTRY_ENVIRONMENT` sets the environment label; its default is `production`. Reports remove exception messages, local installation paths, command arguments, SQL, document content, credentials and request/response data. There is no tracing, profiling or usage analytics.
+
+The CLI reports command failures and uncaught exceptions. Typed input and access errors are excluded; unavailable operations are reported. Some sign-in and network failures still use plain errors and can appear in Sentry. Reporting does not change command output or exit codes. On completion, the CLI waits up to 1 second for pending reports. Delivery is best-effort; a forced exit or offline machine can lose a report.
+
 ## Development and release safety
 
 ```sh
@@ -158,6 +174,6 @@ pnpm --filter @trillioncore/cli test:artifact
 
 The bundle contains its runtime dependencies; no private workspace package is fetched on installation. The artifact test packs it, installs it offline into a temporary directory outside the repository, and invokes the installed executable with isolated HOME/configuration. The disposable PostgreSQL suite additionally runs the installed package through authorization, scoped retrieval, refresh and revocation.
 
-GitHub Actions uses Release Please to open prerelease PRs. Merging a release PR publishes its CLI version under `next`, using the repository Actions secret `NPM_TOKEN`; no local npm login is needed. The **CLI Release** workflow also permits an explicitly approved manual run on `main` with the exact current package version for bootstrap or recovery. It refuses already-published versions rather than retrying an ambiguous publication. Registry integrity, unchanged `latest`, and an isolated registry installation are verified after publishing. See the project npm skill for credential and release boundaries.
+GitHub Actions uses Release Please to open prerelease PRs. Merging a release PR publishes its CLI version under `next`, using the repository Actions secret `NPM_TOKEN`; no local npm login is needed. The **CLI Release** workflow also permits an explicitly approved manual run on `main` with the exact current package version for bootstrap or recovery. It refuses already-published versions rather than retrying an ambiguous publication. Registry integrity, unchanged `latest`, and an isolated registry installation are verified after publishing. The workflow then points `latest` at the verified version and checks that an untagged install gets it. See the project npm skill for credential and release boundaries.
 
-Publication is a separate, approved operation. The source publish hook requires an explicit `--tag next` and a `-next.N` version. Do not replace `latest`, bypass lifecycle checks, or trigger the v0 stable release workflow.
+Publication is a separate, approved operation. The source publish hook requires an explicit `--tag next` and a `-next.N` version. Do not move `latest` by hand, bypass lifecycle checks, or trigger the v0 stable release workflow.