@syncmatters/script-api 1.0.10 → 1.0.12

package/connections/map.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Org connection uid → that connection's generated `Connection` type.
+ *
+ * Empty in this package. `sm types` / the web editor merge keys via
+ * `declare module '@syncmatters/script-api/connections/map'`.
+ */
+export interface ConnectionMap {
+}

package/docs/01-workspace-layout.md

@@ -24,9 +24,9 @@ AGENTS.md           # CLI-generated agent guide (managed block + your notes belo
 | `groups/**/group.config.json` | **No** | **No** |
 | `types/**`, `.sm/`, `package.json`, `jsconfig.json` | **No** | **No** |
 
-Sync and sync-group **configuration** (mappings, schedules, which module is attached) is changed
-in the **web UI** today. The CLI exports snapshots for **read-only context** so agents know what
-is deployed; a future `sm sync …` push workflow is not available yet.
+Sync and sync-group **configuration** is authored in `changes/*.sync-changes.json` and published
+with `sm sync push` after a human reviews `sm sync draft`. Snapshots under `syncs/` and `groups/`
+are **read-only context** — never hand-edit or `sm push` them. Schedules still start in the web UI.
 
 Generated sync/group files include a marker:
 

package/docs/05-reading-sync-snapshots.md

@@ -30,8 +30,22 @@ Each file starts with:
 
 - Do **not** hand-edit snapshots to change mappings, schedules, or wiring.
 - Do **not** `sm push` snapshot paths — there is no push route for them today.
-- Do **not** treat snapshots as the source of truth for writes — the web UI (or future CLI sync
-  commands) owns configuration changes.
+- Do **not** treat snapshots as the source of truth for writes. Author mapping changes in
+  `changes/*.sync-changes.json`, preview with `sm sync draft <file>`, then `sm sync push <file>`
+  only when the human has instructed it. Snapshots stay generated.
+
+## Preview drafts (`sm sync draft`)
+
+Preview writes a second JSON tree (not a pull snapshot):
+
+```
+syncs/<sync_uid>/sync.config.draft.json          # existing sync, after the changeset
+changes/<name>.draft.<handle>.json               # created sync/group (`$` stripped)
+```
+
+`$sm.generated_by` is `"sm sync draft"`. These files are evaluation output — never a `sm push`
+payload. `sm pull` never deletes `*.draft.json` (rename+`--force` relocates them with the uid).
+A rerun of `sm sync draft <file>` replaces `changes/<name>.draft.*.json` for that changeset stem.
 
 ## Refresh
 
@@ -41,5 +55,5 @@ Each file starts with:
 | `sm pull` | Scripts + snapshots (unless `--no-syncs`) |
 | `sm pull sync --force` | Overwrite locally modified **generated** snapshots |
 
-Missing `syncs:read` on the developer token: default pull warns and skips; `sm pull sync` exits
-2 with mint-token guidance.
+Missing `syncs:read` on the developer token: default pull warns and skips; `sm pull sync` and
+`sm sync draft` exit 2 with mint-token guidance.

package/docs/06-cli-workflow-and-tokens.md

@@ -13,7 +13,8 @@ sm pull sync               # optional: refresh sync/group snapshots only
 
 - **Scripts only:** `sm push` uploads changed files under `files/` (and meta sidecars). It does
   **not** upload `syncs/` or `groups/`.
-- **Sync config changes:** web UI (future CLI sync push out of scope).
+- **Sync config changes:** `changes/*.sync-changes.json` → `sm sync draft` → human review →
+  `sm sync push` (needs `syncs:write`). Agents push only on human instruction.
 - **Reading snapshots:** use `syncs/` and `groups/` for context before editing the wired module
   in `files/`.
 
@@ -30,7 +31,8 @@ Prefer tokens **without execute scopes** for day-to-day edit/push work:
 | --- | --- |
 | `scripts:read` | pull, diff incoming |
 | `scripts:write` | push script files |
-| `syncs:read` | `sm pull sync`, sync snapshots |
+| `syncs:read` | `sm pull sync`, sync snapshots, `sm sync draft` |
+| `syncs:write` | `sm sync push` / `applysyncops` (human-approved publish) |
 | `connections:read` | `sm types`, connection resolution |
 | `scripts:execute` | **Only when running** `sm test` / connector features |
 | `syncs:execute` | Reserved; not needed for authoring |
@@ -48,7 +50,7 @@ If the CLI reports **403** with missing scope or "not available to developer tok
 
 Examples:
 
-- Missing `syncs:read` → cannot pull sync snapshots (`sm pull sync`).
+- Missing `syncs:read` → cannot pull sync snapshots (`sm pull sync`) or preview a changeset (`sm sync draft`).
 - Missing `scripts:execute` → cannot run `sm test` (expected if using a read/write-only token).
 
 ## Non-interactive runs

package/lib/context.d.ts

@@ -1,19 +1,27 @@
+import type { ConnectionMap } from "@syncmatters/script-api/connections/map";
+import type { SyncGroupMap } from "@syncmatters/script-api/syncGroups/map";
 import { Connection } from "./connection.js";
 import { SyncGroup } from "./sync-group.js";
 import { Logger } from "./logger.js";
 import { FileProvider } from "./utilities/file-provider/file-provider.js";
+/**
+ * When the org map is empty (no `sm types` overlay), keep a string index so
+ * runners and tests still type `ctx.connections[name]`. Once keys are merged
+ * onto ConnectionMap / SyncGroupMap, those uids become typed factories.
+ */
+export type ContextMapFactories<M, Fallback> = [keyof M] extends [never] ? {
+    [name: string]: () => Promise<Fallback>;
+} : {
+    [P in keyof M]: () => Promise<M[P]>;
+};
 /** Context is passed to the script to provide access to system services such as logging, connections, state and environment information */
 export interface Context {
     log: Logger;
     parameters: {
         [name: string]: any;
     };
-    connections: {
-        [name: string]: () => Promise<Connection>;
-    };
-    syncGroups: {
-        [name: string]: () => Promise<SyncGroup>;
-    };
+    connections: ContextMapFactories<ConnectionMap, Connection>;
+    syncGroups: ContextMapFactories<SyncGroupMap, SyncGroup>;
     state: {
         get(): Promise<any>;
         set(state: any): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/script-api",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "TypeScript type definitions for the SyncMatters script API (types only - scripts execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -15,12 +15,20 @@
     "./api": {
       "types": "./api.d.ts",
       "default": "./index.js"
+    },
+    "./connections/map": {
+      "types": "./connections/map.d.ts",
+      "default": "./index.js"
+    },
+    "./syncGroups/map": {
+      "types": "./syncGroups/map.d.ts",
+      "default": "./index.js"
     }
   },
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "5251aaa77076a0901c2b3221a4be5f4d9a9d9aeb572ef3e59f4952b31e9fffdf",
+  "typesContentHash": "87bf322ba471ad760d94c31884ed28859fb460b28f3558f876ee88423eda1c92",
   "dependencies": {
     "@types/node": "*"
   }

package/syncGroups/map.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Org sync-group uid → `SyncGroup`. Every key is the same runtime type;
+ * the map exists so `ctx.syncGroups.<uid>()` can complete.
+ *
+ * Empty in this package. `sm types` / the web editor merge keys via
+ * `declare module '@syncmatters/script-api/syncGroups/map'`.
+ */
+export interface SyncGroupMap {
+}