@loxtep/sdk 0.7.29 → 0.9.0

package/docs/project-workspace-status.md

@@ -0,0 +1,161 @@
+# Project workspace status (three layers)
+
+Stable snake_case payload for **local / cloud / deployed** visibility.
+
+Canonical TypeScript + Zod: `src/client/project-workspace-status-types.ts`
+(exported from `@loxtep/sdk`).
+
+## Layers
+
+| Layer | Meaning | Source of truth |
+| --- | --- | --- |
+| `local` | CWD / known-locals + `.loxtep/project.json` | Disk |
+| `cloud` | Org project + Studio/S3 workspace | `project_id` + workspace APIs |
+| `deployed` | Instance bindings after `deploy` | Deployments |
+
+**Unpublished** = deltas between layers (not a draft flag):
+
+- `unpublished.local_to_cloud` — Local → Cloud (not pushed / workspace out of date)
+- `unpublished.cloud_to_deployed` — Cloud → Deployed (pushed but not deployed, or stale)
+
+`dirty: null` means **not computed** at this `population_depth`. Do not treat null as clean.
+
+## Consumers
+
+| Surface | Uses |
+| --- | --- |
+| CLI `loxtep status` | Full `ProjectWorkspaceStatus` (`population_depth: "status"`) |
+| CLI `loxtep status --unpublished` / `projects changes` | Same payload at `population_depth: "unpublished"` with file/entity lists |
+| CLI `loxtep projects list\|get` | `ProjectListStatusEnrichment` fields |
+| CLI `loxtep projects link` / `loxtep link` | Local bind + `~/.loxtep/workspaces.json` |
+| MCP `get_project_workspace_status` | Full `ProjectWorkspaceStatus` (planned) |
+| MCP `list_projects` / `get_project` | Enrich with summary fields when cheap (planned) |
+
+Producer helpers live in `src/client/project-workspace-status.ts`
+(`buildProjectWorkspaceStatus`, `formatProjectWorkspaceStatusLines`,
+`enrichProjectListSummary`) and `src/client/project-workspace-inventory.ts`
+(push discovery + `.loxtep/push-manifest.json` compare).
+
+Do **not** invent a second list command; enrich the existing `projects` plural group.
+
+Distinct from CLI/MCP **`observe status`** (runtime bots/queues).
+
+## Link vs attach (Phase C)
+
+| Command | Binds | Writes |
+| --- | --- | --- |
+| `loxtep projects link` / `loxtep link` | Cloud **project** ↔ local directory | `.loxtep/project.json` (`project_id`) + `~/.loxtep/workspaces.json` |
+| `loxtep attach` | Local project ↔ runtime **Instance** | `instance_id` + `api_url` (+ streams) in `.loxtep/project.json` |
+| `loxtep init --project-id` | Same project bind as `link`, plus scaffold dirs | project.json + known-locals upsert |
+
+Canonical flow for an existing unbound cloud project:
+
+```text
+loxtep projects link <project_id|name> [--path .]
+loxtep attach --instance <instance-id>
+# edit local package
+loxtep push
+loxtep deploy
+```
+
+GitHub is optional for `link` (`cloud.github.state` may remain `unbound`).
+
+## Population cost (keep list snappy)
+
+Field costs live in `PROJECT_WORKSPACE_STATUS_FIELD_COST`. Depth ceilings:
+
+| `population_depth` | Cost ceiling | Typical use |
+| --- | --- | --- |
+| `summary` | `cheap` | Every list row: local path presence, github linked\|unbound, attach |
+| `status` | `moderate` | `loxtep status` / MCP get: last deploy id/status/age, dirty **booleans** |
+| `unpublished` | `expensive` | `--unpublished` / `list_project_changes`: entity/file inventories + counts |
+
+**Cheap (list-safe):** cwd / known-locals FS checks; columns already on the cloud
+project list row (`project_id`, `name`, `github_repo_*`).
+
+**Moderate (status/get):** one deploy lookup (or cached join) per project;
+Local→Cloud dirty boolean via package vs `.loxtep/push-manifest.json`
+(same discovery as `loxtep push`) without attaching per-file lists.
+
+**Expensive (opt-in):** `loxtep status --unpublished` / `loxtep projects changes` —
+walk local package vs push manifest (+ optional cloud workflow id escalate),
+attach `unpublished.*.changes` entity/file inventory and counts.
+
+Producers SHOULD omit or set `null` rather than stall list enrichment on moderate/expensive work.
+
+## GitHub linked vs unbound
+
+`cloud.github.state`:
+
+- `linked` — project has GitHub binding (`github_repo_url` / name)
+- `unbound` — no GitHub; Studio/S3 + `loxtep push` path
+
+Attach (`local.attach_state`) is **instance** binding (`loxtep attach`), not GitHub.
+
+## Deploy age / status
+
+`deployed.state`: `never_deployed` | `deployed` | `stale` | `unknown`.
+
+When known: `deployment_id`, `deployment_status`, `last_deployed_at`,
+`age_seconds` (derived). Prefer `unknown` over inventing success when the deploy
+API is unavailable.
+
+## Example (status depth)
+
+```json
+{
+  "schema_version": 1,
+  "population_depth": "status",
+  "project_id": "11111111-1111-1111-1111-111111111111",
+  "display_name": "shopify-ingest",
+  "local": {
+    "presence": "present",
+    "path": "/home/you/proj",
+    "project_file": "/home/you/proj/.loxtep/project.json",
+    "known_local": true,
+    "attach_state": "attached",
+    "instance_id": "22222222-2222-2222-2222-222222222222",
+    "api_url": "https://apidev.loxtep.io",
+    "project_id": "11111111-1111-1111-1111-111111111111"
+  },
+  "cloud": {
+    "presence": "present",
+    "project_id": "11111111-1111-1111-1111-111111111111",
+    "organization_id": "33333333-3333-3333-3333-333333333333",
+    "name": "shopify-ingest",
+    "status": "active",
+    "github": {
+      "state": "unbound",
+      "url": null,
+      "name": null,
+      "branch": null,
+      "last_sync_at": null
+    },
+    "workspace_revision": null,
+    "workspace_updated_at": null
+  },
+  "deployed": {
+    "presence": "absent",
+    "state": "never_deployed",
+    "instance_id": "22222222-2222-2222-2222-222222222222",
+    "deployment_id": null,
+    "deployment_status": null,
+    "last_deployed_at": null,
+    "age_seconds": null
+  },
+  "unpublished": {
+    "local_to_cloud": {
+      "dirty": true,
+      "summary": "Local package has changes not pushed",
+      "changed_count": null
+    },
+    "cloud_to_deployed": {
+      "dirty": false,
+      "summary": "Never deployed",
+      "changed_count": null
+    }
+  },
+  "next_action": "push",
+  "notes": []
+}
+```

package/docs/sdk-mcp-mapping.md

@@ -12,7 +12,7 @@ deprecation aliases.
 | --- | --- | --- |
 | `loxtep_session` | `client.session` | `get_current_user`, `get_current_organization`, `logout` |
 | `loxtep_connect` | `client.connect` | `.connectors.*`, `.templates.*` |
-| `loxtep_workspace` | `client.workspace` | `.projects.*`, `.instances.*`, `.versions` (REST pending) |
+| `loxtep_workspace` | `client.workspace` | `.projects.*`, `.instances.*`, `.versions` (REST pending); planned MCP `get_project_workspace_status` → `ProjectWorkspaceStatus` ([docs](./project-workspace-status.md)) |
 | `loxtep_build` | `client.build` | `.workflows.*`, `.triggers.*`, `.data_products.*`, `.targets.*`, deploy writes, `.get_writer({ bot_id, queue })` escape hatch |
 | `loxtep_define` | `client.define` | `.schemas.*`, `.quality.*`, `.standards.*`, `.data_contracts.*`, `.domains.*` |
 | `loxtep_meaning` | `client.meaning` | `.thesaurus.*` (ontology/semantic REST split pending) |
@@ -35,7 +35,9 @@ Same on Python: `client.get_writer("orders_raw")`, `client.get_reader("orders_ra
 Low-level workflow writer escape hatch: `client.build.get_writer(workflow_id, { bot_id, output_queue_name, … })`.
 
 Vocabulary: MCP `loxtep_build` trigger operations (backend: connections) and target operations
-(backend: consumptions). Connector OAuth uses `get_oauth_url`; sample capture uses `capture_samples`.
+(backend: consumptions). Connector OAuth uses `get_oauth_url`; connectivity
+probe uses `test_connector` / `loxtep connectors test <id>`; sample capture uses
+`capture_samples` / `loxtep connectors capture-samples <id> --entity-type <name>`.
 
 When unsure: **MCP for provisioning and agent tool calls**; **SDK for runtime**
 services running in your infrastructure or CI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loxtep/sdk",
-  "version": "0.7.29",
+  "version": "0.9.0",
   "description": "Loxtep SDK for Node.js — the Enterprise Context Layer: data products, workflows, projects, queues, and machine-usable context for AI",
   "author": "Loxtep <engineering@loxtep.io>",
   "homepage": "https://loxtep.io",

package/schemas/entity-json-schemas/SCHEMA_SYNC.md

@@ -3,8 +3,9 @@
 These JSON Schema draft-07 files are a copy of the Loxtep platform schemas used
 for customer workspace entity validation.
 
-**Source (canonical):**
-`loxtep/platform-backend/_core/src/customer-workspace/entity-json-schemas/`
+**Source (canonical):** Loxtep platform customer-workspace entity JSON schemas
+(private platform monorepo). Sync from a local checkout when those schemas
+change.
 
 **Sync command** (from `nodejs/`):
 
@@ -15,4 +16,4 @@ node scripts/sync-entity-schemas.mjs /path/to/loxtep
 When platform schemas change, re-run the sync script and note the date/source
 commit in the SDK CHANGELOG.
 
-**Last synced:** 2026-07-24 (from local loxtep checkout)
+**Last synced:** 2026-07-24 (from local Loxtep platform checkout)

package/schemas/entity-json-schemas/data-product.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://loxtep.io/schemas/entity/data-product.json",
   "title": "Data Product Entity",
-  "description": "JSON Schema for Data Product entity in customer workspace (Studio / S3 graph). Flow-graph fields (workflow_id, upstream_entity_id, etc.) describe placement in the workflow canvas. The canonical interoperable catalog and API representation is ODPS v4.1 (Open Data Products Standard): include `odps_document` aligned with https://opendataproducts.org/v4.1/schema/odps.json — see `odps-product.json` and .kiro/specs/odps-data-product-standard in the Loxtep repo.",
+  "description": "JSON Schema for Data Product entity in customer workspace (Studio / S3 graph). Flow-graph fields (workflow_id, upstream_entity_id, etc.) describe placement in the workflow canvas. The canonical interoperable catalog and API representation is ODPS v4.1 (Open Data Products Standard): include `odps_document` aligned with https://opendataproducts.org/v4.1/schema/odps.json — see `odps-product.json` in this package for the ODPS document shape.",
   "type": "object",
   "required": [
     "data_product_id",

package/schemas/entity-json-schemas/odps-product.json

@@ -3,7 +3,7 @@
   "$id": "https://loxtep.io/schemas/entity/odps-product.json",
   "title": "ODPS v4.1 Data Product Document",
   "x-canonical-json-schema": "https://opendataproducts.org/v4.1/schema/odps.json",
-  "description": "Open Data Products Standard (ODPS) v4.1 root document (`product.*`). Authoritative JSON Schema: https://opendataproducts.org/v4.1/schema/odps.json . Loxtep platform types and mapping: platform-backend/_core/src/types/odps/ and .kiro/specs/odps-data-product-standard. Platform-specific fields live under `product.custom.loxtep` (medallion, storage, ingestion, organization_id, domain_id, project_id, workflow_id, etc.). For strict full-schema validation in toolchains that resolve remote $ref, compose with allOf + $ref to x-canonical-json-schema (requires network or bundled copy).",
+  "description": "Open Data Products Standard (ODPS) v4.1 root document (`product.*`). Authoritative JSON Schema: https://opendataproducts.org/v4.1/schema/odps.json . Platform-specific fields live under `product.custom.loxtep` (medallion, storage, ingestion, organization_id, domain_id, project_id, workflow_id, etc.). For strict full-schema validation in toolchains that resolve remote $ref, compose with allOf + $ref to x-canonical-json-schema (requires network or bundled copy).",
   "type": "object",
   "required": ["product"],
   "additionalProperties": false,