syncrona

| | | | | | | |:--:|:--:|:--:|:--:|:--:|:--:|

This module contains the core of SyncroNow AI. It is required to use SyncroNow AI at all. It can interact with other plugins after you configure them.

It ships the syncrona CLI. The full command reference lives in the root README; the 1.1 additions at a glance:

• init --new --name "<display>" creates a new scoped application on the instance and binds the directory to it (--dry-run prints the sys_app body).
• push --create creates (or adopts) records for files not in the manifest yet; push --prune deletes in-scope records whose tracked files git shows deleted (see Creating and deleting records).
• query <table> reads any table with the now-sdk query flags.
• cicd <action> runs ATF suites and tests and installs, publishes or rolls back applications through the CI/CD API.
• fluent <action> drives Fluent (.now.ts) apps through the optional @syncrona/fluent tier; fluent types --native generates table types without it.
• Records get an editable .meta.json sidecar holding their non-file columns (see the root README's "Data model").

Credential resolution order

Commands resolve ServiceNow credentials in this order (first match wins):

1. --instance-profile <name> → SN_INSTANCE_<NAME> / SN_USER_<NAME> / SN_PASSWORD_<NAME> environment variables;
2. plain SN_INSTANCE / SN_USER / SN_PASSWORD environment variables (a .env in the project root is loaded into the environment at startup);
3. the global encrypted credential store (syncrona login, syncrona use).

Project-local sources deliberately beat the global store, and the MCP server follows the same precedence (see the mcp-server README).

Push recovery and locking

syncrona push maintains two state files in the project root (next to sync.config.js); both are safe to delete when no push is running:

• sync.push.checkpoint.json — written after you confirm a push, updated with the per-record outcome, and removed when every record succeeds. If a push is interrupted or partially fails, the next push offers to resume only the failed records. Declining a confirmation prompt leaves no checkpoint behind.
• sync.collaboration.lock.json — an atomically-created lock that prevents two concurrent pushes against the same workspace. It is staged under a private name and published with a hard link, so a collaborator can never observe it half-written. A crash cannot leave it behind for long: a lock whose owning process no longer exists is reclaimed immediately, and locks older than 30 minutes are treated as stale and replaced automatically.

Creating and deleting records

By default push only updates records the manifest already tracks.

• --create (or createRecords: true in sync.config.js; --no-create wins over it) also creates records for local files in the manifest layout that no record claims yet. A single in-scope record with the same display name is adopted into the manifest instead of duplicated.
• --prune is destructive: it deletes the in-scope records whose tracked files git shows deleted. It confirms first unless --ci, refuses more than 25 deletions or 20% of the manifest unless --allow-mass-delete, and has no config switch. Preview with push --prune --dry-run.

Push retries only network errors and retryable HTTP statuses (5xx/408/429); authentication failures fail fast instead of being retried.

Update notifications

The CLI performs a best-effort check for a newer published version at most once per day and, when one is available, prints a single notice to stderr (it never writes to stdout, so piped output stays clean). The check is non-blocking, swallows all failures, and never prevents a command from running.

The notifier is automatically skipped when:

• running in CI (CI is set) or under tests (JEST_WORKER_ID is set), or
• stderr is not an interactive terminal (e.g. output is piped).

To opt out explicitly, set either of these environment variables to 1 or true:

• SYNCRONA_NO_UPDATE_NOTIFIER
• NO_UPDATE_NOTIFIER

The last check is cached in ~/.syncrona/update-check.json.

Environment variables

Authentication method selection

SN_AUTH_METHOD selects the ServiceNow inbound REST auth method: basic (default), oauth-password, oauth-client-credentials, oauth-jwt-bearer, or api-key or bearer. When unset it is inferred for backward compatibility (bearer when SN_BEARER_TOKEN is set, then OAuth password when a client id/secret pair and a password are present, otherwise Basic). An unrecognized value is reported as a configuration issue (syncrona doctor, MCP server startup) instead of falling back to inference. Every variable below also accepts a per-profile _<NAME> suffix.

| Variable | Method | Purpose | | --- | --- | --- | | SN_OAUTH_CLIENT_ID / SN_OAUTH_CLIENT_SECRET | oauth-* | OAuth client id/secret (reused by password, client-credentials, jwt-bearer). | | SN_API_KEY | api-key | Inbound REST API key value. | | SN_API_KEY_HEADER | api-key | Header name override (default x-sn-apikey). | | SN_BEARER_TOKEN | bearer | Pre-issued OAuth access token sent as Authorization: Bearer; env-only, never stored or refreshed. | | SN_JWT_KEY | oauth-jwt-bearer | Path to (or inline) RS256 private-key PEM used to sign the assertion. | | SN_JWT_KID / SN_JWT_ISS / SN_JWT_SUB / SN_JWT_AUD | oauth-jwt-bearer | Optional JWT header kid and iss/sub/aud claim overrides (defaults derived from client id + user + instance). | | SN_CLIENT_CERT / SN_CLIENT_KEY | mTLS | Client certificate + private-key PEM paths (mutual TLS, combinable with any method). | | SN_CLIENT_KEY_PASSPHRASE | mTLS | Passphrase for an encrypted client key. | | SN_SESSION_COOKIE / SN_SESSION_TOKEN | Fluent tier | An injected UI session (Cookie header and X-UserToken), handed to the SDK as is ahead of the profile's method; env-only, un-suffixed, never stored or renewed. Other commands ignore it. |

SN_JWT_KEY, SN_CLIENT_CERT and SN_CLIENT_KEY are file paths — the key material is read at request time and never copied into the credential store.

Other variables

Besides the credential variables above (SN_INSTANCE / SN_USER / SN_PASSWORD and their named SN_*_<NAME> forms), the auth-method variables, and the update-notifier opt-outs, the core CLI reads:

| Variable | Purpose | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SYNCRONA_DATA_TABLES | Comma-separated allowlist of table names whose data records are materialized into the manifest (e.g. x_my_table,sys_choice). Empty/unset materializes none by default. | | SYNCRONA_INCLUDE_DATA_FIELDS | Materialize data fields for all tables. Truthy (1/true/yes/on) enables it; falsey (0/false/no/off) disables. Unset falls back to the allowlist above. | | SYNCRONA_MCP_SERVER_PATH | Explicit path to the MCP server entry (dist/index.js) used by syncrona mcp. Overrides the built-in workspace/node_modules lookup; useful for local development. |