@hasna/contacts 0.6.36 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @hasna/contacts
 
-Contact management for AI coding agents — CLI + MCP + Web
+Contact management for AI coding agents — CLI + MCP + authenticated HTTP API
 
 [![npm](https://img.shields.io/npm/v/@hasna/contacts)](https://www.npmjs.com/package/@hasna/contacts)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
@@ -11,12 +11,38 @@ Contact management for AI coding agents — CLI + MCP + Web
 npm install -g @hasna/contacts
 ```
 
+## Configure the client
+
+Every CLI, MCP, and package data operation uses one authenticated HTTPS `/v1`
+authority. There is no built-in hosted URL and no local database fallback.
+
+```bash
+export HASNA_CONTACTS_API_URL="https://contacts.example.com"
+# Provision the API key through the @hasna/contracts credential chain. For
+# example, put HASNA_CONTACTS_API_KEY in the shared fleet/config credential chain,
+# or configure HASNA_CONTACTS_API_KEY_REF for the secrets client.
+contacts connection --json
+```
+
+An absent or invalid URL/key fails closed. `HASNA_CONTACTS_STORAGE_MODE`,
+`CONTACTS_STORAGE_MODE`, contacts DB-path variables, and contacts database URLs
+are rejected in client processes. PostgreSQL URLs belong only to
+`contacts-serve` and the migration task.
+
 ## CLI Usage
 
 ```bash
+contacts status            # CLI version, API endpoint, storage mode, record counts
+contacts status --json
 contacts --help
 ```
 
+`contacts status` answers even on a box without an API key: an unconfigured
+client reports storage `unconfigured` (a failed request on a configured box
+reports storage `error` with the failure message) instead of crashing, so
+agents can observe the configuration drift the command exists to expose.
+
+
 ## Audiences, consent, and suppression
 
 Audience segments implement the `hasna.audience.v1` contract (distribution
@@ -63,7 +89,7 @@ MCP_HTTP=1 contacts-mcp
 - Health: `GET http://127.0.0.1:8809/health`
 - MCP: `http://127.0.0.1:8809/mcp`
 
-The REST server (`contacts-serve`) also exposes `/health` and `/mcp` when running.
+The REST server is a separate authenticated `/v1` surface.
 
 ## REST API
 
@@ -72,83 +98,41 @@ contacts-serve
 ```
 
 `contacts-serve` binds to `127.0.0.1` by default. Use `--host <host>` or
-`CONTACTS_HOST=<host>` only when intentionally exposing it beyond loopback.
-Shared binds still fail closed unless a valid contacts token is configured and
-sent with the request. The unauthenticated local development fallback is disabled
-by default and only activates when all of the following are true:
-
-- no contacts API token environment variable is configured
-- `CONTACTS_ALLOW_UNAUTHENTICATED_LOOPBACK=1`
-- the server is explicitly bound to a loopback host
-
-The fallback does not trust the HTTP `Host` header.
+`CONTACTS_HOST=<host>` only when intentionally exposing it beyond loopback. The
+server requires PostgreSQL configuration and API-key signing configuration;
+readiness fails closed when either is unavailable.
 
-## Storage
+## Storage and legacy data
 
-Contacts owns its local SQLite storage directly. It does not depend on shared
-cloud runtime commands or MCP tools.
+The client never opens SQLite or PostgreSQL. The server owns PostgreSQL and all
+authoritative data remains server-side. Inspect the value-free connection state
+with:
 
 ```bash
-contacts storage status
-contacts storage status --json
-contacts storage push --tables contacts,companies
-contacts storage pull --tables contacts,companies
-contacts storage sync
+contacts connection --json
 ```
 
-Optional cross-machine sync uses contacts-owned PostgreSQL storage. Set one of:
+Retired local databases are never auto-adopted or silently ignored. The
+explicit migration aid only inspects and copies them; it never opens, changes,
+deletes, or selects one as the live store:
 
 ```bash
-export HASNA_CONTACTS_POSTGRES_URL="postgres://..."
-# or OPEN_CONTACTS_POSTGRES_URL / CONTACTS_POSTGRES_URL
+contacts legacy inspect --json
+contacts legacy preserve --source /exact/path/contacts.db \
+  --output /existing/directory/contacts.db.pre-https.20260901
 ```
 
-Remote PostgreSQL connections require verified TLS for non-local hosts. Local
-PostgreSQL development URLs can disable TLS explicitly.
-
-By default, remote sync covers contacts, companies, tags, and the other
-non-sensitive relationship tables. `webhooks`, `contact_documents`, and
-`contact_health` are excluded until explicitly requested with `--tables` and
-`HASNA_CONTACTS_ALLOW_SENSITIVE_SYNC=1`. Sync inserts or updates rows with
-timestamp conflict protection. Deletes for `contacts`, `companies`, and `tags`
-write `_contacts_tombstones`; push/pull sync carries those tombstones and pull
-applies them unless the local row has a newer `updated_at`.
-
-Shared REST/dashboard deployments must set one of
-`HASNA_CONTACTS_API_TOKENS`, `OPEN_CONTACTS_API_TOKENS`, or
-`CONTACTS_API_TOKENS`. Values are comma-separated `token=scope scope` records.
-Supported scopes include `contacts:read`, `contacts:write`,
-`contacts:import`, `contacts:export`, `contacts:export:full`,
-`documents:read`, `images:read`, `images:write`, `companies:*`, `tags:*`,
-`stats:read`, `dashboard:read`, and `mcp:access`. Loopback-only development
-without configured tokens remains allowed; shared hosts fail closed.
-
-Server exports are redacted by default: email addresses, phone numbers,
-addresses, notes, birthdays, social profiles, and custom fields are withheld.
-Full exports require both `contacts:export` and `contacts:export:full`. Export,
-import, document file read, image mutation, contact mutation, company mutation,
-and tag mutation routes write audit entries. Document attachments are served
-only from the managed contacts documents directory and use private `no-store`
-cache headers.
-
-`contacts cloud status`, `contacts cloud push`, `contacts cloud pull`, and
-`contacts cloud sync` remain compatibility aliases for the contacts-owned
-storage commands. They do not load or depend on the deprecated shared cloud
-runtime. `contacts cloud feedback` saves feedback locally in the contacts
-database.
-
-## Data Directory
-
-On-box data resolves through the XDG dirs per `@hasna/paths`:
-
-- documents, the SQLite store, `config.json` and the vault config live in the
-  **XDG data root**: `~/.local/share/hasna/contacts/` (or `$HASNA_DATA_HOME/contacts`).
-- the vault session state lives in the **XDG state root**:
-  `~/.local/state/hasna/contacts/` (or `$HASNA_STATE_HOME/contacts`).
-
-The legacy `~/.hasna/contacts/` home is never written to; on first use any
-pre-existing legacy store is adopted into the XDG roots (never clobbering an
-existing XDG store).
+If a SQLite WAL, journal, or shared-memory sidecar is present, preservation
+refuses to proceed until every legacy process is stopped and the old client has checkpointed the database. To move
+portable contact records, use a legacy release against the preserved copy to
+export JSON, then run `contacts import exported.json` with the HTTPS client
+configured. Existing files are never overwritten.
+
+Preservation rejects source, ancestor, or output replacement races and verifies
+the copied bytes with SHA-256 and stable output metadata before success. If a copy
+fails after output creation, any private partial output is left untouched and
+reported as unverified for manual inspection; the command never deletes a
+pathname that another process might have replaced.
 
 ## License
 

package/dist/cli/commands/advanced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/advanced.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAs5B/D"}
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/advanced.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiBzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAq5B/D"}

package/dist/cli/commands/core.d.ts

@@ -1,3 +1,3 @@
 import type { Command } from "commander";
-export declare function registerCoreCommands(program: Command): void;
+export declare function registerCoreCommands(program: Command, version: string): void;
 //# sourceMappingURL=core.d.ts.map

package/dist/cli/commands/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/core.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA87B3D"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/core.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAg4B5E"}

package/dist/cli/commands/crm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crm.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/crm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAm+B1D"}
+{"version":3,"file":"crm.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/crm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAi+B1D"}