@gotillit/tllt 0.3.0

package/AGENTS.md

@@ -0,0 +1,59 @@
+# TilliT CLI — agent guide
+
+You are driving `tllt` (`@gotillit/tllt`), a tool for managing TilliT
+configuration across two APIs: **Digital Operations (DO)** and **Scheduler**.
+
+## How to use this tool effectively
+
+1. **Always pass `--json`.** Structured results go to **stdout**; human progress
+   goes to stderr. On failure you get `{"ok": false, "error": "..."}` and a
+   non-zero exit code. (Or set `TILLIT_JSON=1`.)
+2. **Everything is flag-driven** — never rely on interactive prompts. Supply all
+   required flags and commands run non-interactively.
+3. **Select a connection with `--profile <name>`** (or rely on the default).
+
+## The golden path
+
+```bash
+tllt configure --tenant <t> --environment <env> --auth basic \
+  --username <u> --password <p> --default      # bootstrap a connection (once)
+
+tllt --json import --profile <t>-<env>   # snapshot live config to files
+tllt --json diff --from <A> --to <B>     # changeset to make B look like A
+tllt --json deploy --from <A> --to <B> --dry-run   # preview
+tllt --json deploy --from <A> --to <B> --yes       # apply
+```
+
+## Read these for detail
+
+- [`docs/commands.md`](docs/commands.md) — every command, flag, and JSON shape
+- [`docs/schemas.md`](docs/schemas.md) — **how to learn each entity's data model** (read before editing records)
+- [`docs/authentication.md`](docs/authentication.md) — basic vs api-key/Cognito
+- [`docs/workflow.md`](docs/workflow.md) — snapshot layout, diff/deploy semantics
+- [`docs/apis.md`](docs/apis.md) — the two APIs and what each owns
+- [`docs/scheduler.md`](docs/scheduler.md) — how scheduler config differs (important & different)
+
+## Things that will bite you if you forget
+
+- Before creating/editing a record, **read its schema** — either the
+  `_schema.json` in the same folder or `tllt schema <Entity>`. It tells you
+  required fields, enums, and what each nested `{name}` reference points at.
+- A **connection = environment + tenant**; the profile name is `{tenant}-{environment}`.
+- `deploy` matches records across environments by **natural key** (the `name`,
+  used as the filename), because volatile `id`/`createdAt`/`updatedAt` are
+  stripped on import.
+- `deploy` **never deletes** unless you pass `--prune`.
+- **Scheduler config is organised per `DataTemplate`** and driven through the
+  normalized REST API (`/{locationCode}/{dataTemplateId}/{entity}`). Snapshots
+  nest under the template name; global entities (`Location`, `DataTemplate`,
+  `OptimisationProfile`) sit at the top. Deploy creates a missing template and
+  applies records in dependency order (parents first). See `docs/scheduler.md`.
+- **For scheduler records, `schema` IS authoritative.** Write shapes match the
+  published schema. Nested references are stored by natural key
+  (`{ "name": "Bottling" }`) and the CLI resolves them to the target's id on
+  deploy. A referenced parent must be in the same deploy or already on the target.
+- **Changeover set binds to equipment via the `changeoverSet` ref on create** (a
+  required FK — equipment can't be created without it); it persists, no separate
+  step. **Availability does NOT** bind via the normalized API — use the gateway
+  `availabilities` + `equipment-availabilities` endpoints (≈1yr horizon). See
+  `docs/scheduler.md` → "Binding changeover sets & availability to equipment".

package/README.MD

@@ -0,0 +1,106 @@
+# TilliT CLI
+
+Manage TilliT configuration across the **Digital Operations (DO)** and **Scheduler**
+APIs. Built to be friendly for both humans and AI agents: bootstrap a connection once,
+then `import` → `diff` → `deploy`.
+
+## Install
+
+```bash
+npm install -g @gotillit/tllt      # or run ad-hoc with: npx @gotillit/tllt <command>
+```
+
+## First run — bootstrap a connection
+
+A **connection is identified by environment + tenant**, so you can keep several side by
+side (e.g. `client1` on prod and `client2` on stage). Profiles are stored in
+`~/.tillit/config.json` and named `{tenant}-{environment}`.
+
+Interactive:
+
+```bash
+tllt configure
+```
+
+Non-interactive (agent-friendly) — basic auth:
+
+```bash
+tllt configure --tenant client1 --environment prod \
+  --auth basic --username alice --password '••••' --default
+```
+
+Non-interactive — API key + secret (Cognito `client_credentials` → bearer token):
+
+```bash
+tllt configure --tenant client2 --environment stage \
+  --auth apikey --api-key <cognitoClientId> --api-secret <secret> \
+  --token-url https://<domain>.auth.<region>.amazoncognito.com/oauth2/token \
+  --scopes 'api/*.read,api/*.write'
+```
+
+List connections:
+
+```bash
+tllt profiles
+```
+
+## Authentication
+
+| Method   | How it authenticates                                                            | APIs        |
+| -------- | ------------------------------------------------------------------------------- | ----------- |
+| `basic`  | `Authorization: Basic base64(username@{tenant}.tillit.cloud:password)`          | DO          |
+| `apikey` | Cognito `client_credentials` → cached bearer token; `tillit-tenant` header set  | DO + Scheduler |
+
+Tokens obtained via `apikey` are cached in `~/.tillit/tokens.json` until shortly before
+they expire.
+
+## Workflow
+
+```bash
+# 1. Snapshot the live configuration into ./{profile}/ (the current directory)
+tllt import --profile client2-stage         # use --dir <path> to write elsewhere
+
+# 2. Compare two snapshots (desired -> target) and review the changeset
+tllt diff --from client2-stage --to client1-prod
+
+# 3. Apply the difference to the live target
+tllt deploy --from client2-stage --to client1-prod --dry-run   # preview
+tllt deploy --from client2-stage --to client1-prod             # apply (asks to confirm)
+tllt deploy --from client2-stage --to client1-prod --prune -y  # also delete extras, no prompt
+```
+
+Snapshots are written to the **current directory** (override with `--dir`), so you can keep
+config in its own git repo. They live under `./{profile}/{api}/{Entity}/…` with a `_meta.json` per entity
+recording how to route writes. Volatile fields (`id`, `createdAt`, `updatedAt`) are
+stripped on import, so a content difference reflects a real configuration change. Records
+are matched across environments by their natural key (the `name`, used as the filename).
+
+## Agent-friendly notes
+
+- Add `--json` to any command for machine-readable output on **stdout** (progress goes to
+  stderr). Errors are emitted as `{ "ok": false, "error": "…" }` with a non-zero exit code.
+- All commands are fully flag-driven — no interactive prompts when the required flags are
+  supplied. Set `TILLIT_JSON=1` to force JSON mode.
+- `--profile <name>` selects a connection; otherwise the default profile is used.
+
+## Documentation (for humans and AI agents)
+
+Agent-readable guides live alongside the code:
+
+- [`AGENTS.md`](AGENTS.md) — start here: golden path + gotchas
+- [`docs/commands.md`](docs/commands.md) — full command/flag/JSON reference
+- [`docs/schemas.md`](docs/schemas.md) — how to learn each entity's data model
+- [`docs/authentication.md`](docs/authentication.md) — basic vs api-key/Cognito
+- [`docs/workflow.md`](docs/workflow.md) — snapshot layout + diff/deploy semantics
+- [`docs/apis.md`](docs/apis.md) — the DO and Scheduler APIs
+- [`docs/scheduler.md`](docs/scheduler.md) — Scheduler's dataTemplate scoping
+
+## Commands
+
+| Command     | Description                                                       |
+| ----------- | ----------------------------------------------------------------- |
+| `configure` | Bootstrap or update a connection (alias: `init`)                  |
+| `profiles`  | List configured connections (alias: `connections`)               |
+| `import`    | Snapshot a connection's current configuration into local files   |
+| `diff`      | Compare two snapshots and show the changeset                      |
+| `deploy`    | Apply the difference between two snapshots to the live target     |

package/configure.js

@@ -0,0 +1,243 @@
+import {input, select, password, confirm} from '@inquirer/prompts';
+
+import {
+  ENVIRONMENTS,
+  ENTERPRISE_TIERS,
+  defaultBaseUrl,
+  profileName,
+  saveProfile,
+  listProfiles,
+} from './lib/config.js';
+import {apiClient} from './lib/client.js';
+import {info, result, isJsonMode} from './lib/output.js';
+
+/**
+ * Bootstrap (or update) a connection. A connection is identified by
+ * environment + tenant, so you can keep several side by side, e.g. client1 on
+ * prod and client2 on stage.
+ *
+ * Fully interactive with no flags (first-run bootstrap); fully non-interactive
+ * when the required flags are supplied (agent-friendly).
+ *
+ * Flags: --tenant --environment --auth basic|apikey
+ *   basic:  --username --password
+ *   apikey: --api-key --api-secret --token-url [--scopes a,b]
+ *   common: --base-url (override) --default
+ */
+const doConfigure = async (opts = {}) => {
+  const answers = await collectAnswers(opts);
+
+  const {tenant, environment, enterprise, tier} = answers;
+  const baseUrl = answers.baseUrl || defaultBaseUrl(tenant, environment, {enterprise, tier});
+  const name = profileName(tenant, environment, {enterprise, tier});
+
+  const profile = {tenant, environment, baseUrl, auth: buildAuth(answers)};
+  if (environment === 'enterprise') {
+    profile.enterprise = enterprise;
+    profile.tier = tier || 'stage';
+  }
+  saveProfile(name, profile, {makeDefault: answers.makeDefault});
+
+  info(`\nSaved connection "${name}" (${answers.method} auth) → ${baseUrl}`);
+
+  // Smoke-test the connection so a bad host/credential is caught now, not on
+  // the first import. Querying sites is a cheap, always-present DO endpoint.
+  const test = await testConnection({name, ...profile});
+  if (test.ok) {
+    info(`Connection test: OK — ${test.count} site(s) returned.`);
+  } else {
+    info(`Connection test: FAILED — ${test.error}`);
+    info('The connection was saved anyway; fix the details and re-run configure if needed.');
+  }
+
+  info('\nNext steps:');
+  info(`  tllt import --profile ${name}     # snapshot the current configuration`);
+  info(`  tllt diff   --profile ${name}     # see local vs live changes`);
+  info(`  tllt deploy --profile ${name}     # apply the changes`);
+
+  result(`Connection "${name}" configured.`, {
+    ok: true,
+    profile: name,
+    tenant,
+    environment,
+    baseUrl,
+    authMethod: answers.method,
+    test,
+    profiles: listProfiles(),
+  });
+};
+
+/**
+ * Verify a freshly-saved connection by querying sites (a small, always-present
+ * DO endpoint). Resolves credentials/token too, so it catches bad hosts, wrong
+ * passwords, and Cognito misconfig. Never throws — returns {ok, count|error}.
+ */
+async function testConnection(profile) {
+  try {
+    const client = await apiClient(profile, 'do');
+    const data = await client.get('core/sites', {searchParams: {size: 1000}}).json();
+    const sites = Array.isArray(data) ? data : data?.content ?? [];
+    return {ok: true, count: sites.length};
+  } catch (err) {
+    const status = err.response?.statusCode;
+    return {ok: false, error: status ? `HTTP ${status}: ${err.message}` : err.message};
+  }
+}
+
+function buildAuth(a) {
+  if (a.method === 'basic') {
+    return {method: 'basic', username: a.username, password: a.password};
+  }
+  return {
+    method: 'apikey',
+    apiKey: a.apiKey,
+    apiSecret: a.apiSecret,
+    tokenUrl: a.tokenUrl,
+    scopes: a.scopes,
+  };
+}
+
+async function collectAnswers(opts) {
+  const flags = normalizeFlags(opts);
+  // If the essentials are present we run fully non-interactive.
+  if (canRunNonInteractive(flags)) {
+    validateNonInteractive(flags);
+    return flags;
+  }
+  if (isJsonMode()) {
+    throw new Error(
+      'Missing required flags for non-interactive configure. Provide --tenant, --environment, --auth and the matching credential flags.'
+    );
+  }
+  return promptForAnswers(flags);
+}
+
+function normalizeFlags(opts) {
+  const scopes = opts.scopes
+    ? String(opts.scopes)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : undefined;
+  return {
+    tenant: opts.tenant,
+    environment: opts.environment,
+    enterprise: opts.enterprise,
+    tier: opts.tier,
+    method: opts.auth,
+    username: opts.username,
+    password: opts.password,
+    apiKey: opts.apiKey,
+    apiSecret: opts.apiSecret,
+    tokenUrl: opts.tokenUrl,
+    scopes,
+    baseUrl: opts.baseUrl,
+    makeDefault: Boolean(opts.default),
+  };
+}
+
+function canRunNonInteractive(f) {
+  if (!f.tenant || !f.environment || !f.method) return false;
+  if (f.environment === 'enterprise' && !f.enterprise) return false;
+  if (f.method === 'basic') return Boolean(f.username && f.password);
+  if (f.method === 'apikey') return Boolean(f.apiKey && f.apiSecret && f.tokenUrl);
+  return false;
+}
+
+function validateNonInteractive(f) {
+  if (!ENVIRONMENTS.includes(f.environment)) {
+    throw new Error(`--environment must be one of: ${ENVIRONMENTS.join(', ')}`);
+  }
+  if (f.environment === 'enterprise') {
+    if (!f.enterprise) throw new Error('--enterprise <name> is required when --environment enterprise');
+    if (f.tier && !ENTERPRISE_TIERS.includes(f.tier)) {
+      throw new Error(`--tier must be one of: ${ENTERPRISE_TIERS.join(', ')}`);
+    }
+  }
+  if (!['basic', 'apikey'].includes(f.method)) {
+    throw new Error('--auth must be "basic" or "apikey"');
+  }
+}
+
+async function promptForAnswers(flags) {
+  const merged = {...flags};
+
+  if (!merged.tenant) {
+    merged.tenant = await input({message: 'Tenant', validate: req});
+  }
+  if (!merged.environment) {
+    merged.environment = await select({
+      message: 'Environment',
+      choices: ENVIRONMENTS.map((v) => ({name: v, value: v})),
+    });
+  }
+  if (!merged.method) {
+    merged.method = await select({
+      message: 'Authentication method',
+      choices: [
+        {name: 'Username + password (basic auth)', value: 'basic'},
+        {name: 'API key + secret (Cognito bearer token)', value: 'apikey'},
+      ],
+    });
+  }
+
+  // Enterprise (dedicated) environments need an enterprise name + tier so the
+  // base URL becomes {tenant}.{enterprise}.tillit-{tier}.cloud.
+  if (merged.environment === 'enterprise') {
+    if (!merged.enterprise) {
+      merged.enterprise = await input({message: 'Enterprise name (e.g. acme)', validate: req});
+    }
+    if (!merged.tier) {
+      merged.tier = await select({
+        message: 'Underlying tier',
+        choices: ENTERPRISE_TIERS.map((v) => ({name: v, value: v})),
+        default: 'stage',
+      });
+    }
+  }
+
+  if (merged.method === 'basic') {
+    if (!merged.username) {
+      merged.username = await input({message: 'Username', validate: req});
+    }
+    if (!merged.password) {
+      merged.password = await password({message: 'Password', validate: req});
+    }
+  } else {
+    if (!merged.apiKey) {
+      merged.apiKey = await input({message: 'API key (Cognito app client id)', validate: req});
+    }
+    if (!merged.apiSecret) {
+      merged.apiSecret = await password({message: 'API secret', validate: req});
+    }
+    if (!merged.tokenUrl) {
+      merged.tokenUrl = await input({
+        message: 'Cognito OAuth2 token URL (…/oauth2/token)',
+        validate: req,
+      });
+    }
+  }
+
+  if (!merged.baseUrl) {
+    const value = await input({
+      message: `Base URL [default ${defaultBaseUrl(merged.tenant, merged.environment, {enterprise: merged.enterprise, tier: merged.tier})}]`,
+      default: '',
+    });
+    merged.baseUrl = value.trim() || undefined;
+  }
+
+  if (!merged.makeDefault) {
+    merged.makeDefault = await confirm({
+      message: 'Make this the default connection?',
+      default: true,
+    });
+  }
+
+  return merged;
+}
+
+function req(value) {
+  return value && String(value).trim() ? true : 'Required';
+}
+
+export default doConfigure;

package/deploy.js

@@ -0,0 +1,289 @@
+import fs from 'fs';
+import {confirm} from '@inquirer/prompts';
+
+import {resolveProfile} from './lib/config.js';
+import {apiClient} from './lib/client.js';
+import {computeChangeset} from './diff.js';
+import {info, result, isJsonMode} from './lib/output.js';
+import {
+  getSchedulerEntity,
+  idRefs,
+  resolveRefs,
+  matchKey,
+  expandParam,
+  scopeRows,
+  schedulerDeployOrder,
+} from './lib/scheduler-entities.js';
+
+/**
+ * Apply the difference between two snapshots to a live target. The target is
+ * the `--to` profile (the system being changed); the desired state is the
+ * `--from` snapshot.
+ *
+ *   tllt deploy --from acme-stage --to acme-prod            # apply
+ *   tllt deploy --from acme-stage --to acme-prod --dry-run  # plan only
+ *   tllt deploy --changeset plan.json --to acme-prod        # from a saved plan
+ *
+ * Because volatile ids are stripped on import, deploy resolves the target id
+ * for updates/deletes by matching the record's natural key (its `name`, the
+ * same value used as the snapshot filename) against the live collection.
+ *
+ * Deletes are opt-in (`--prune`) so a partial snapshot never wipes live config.
+ */
+const doDeploy = async (opts = {}) => {
+  const to = opts.to;
+  if (!to) throw new Error('deploy requires --to <profile> (the target to change).');
+
+  let changes;
+  if (opts.changeset) {
+    changes = JSON.parse(fs.readFileSync(opts.changeset, 'utf8')).changes;
+  } else if (opts.from) {
+    changes = computeChangeset(opts.from, to, opts);
+  } else {
+    throw new Error('deploy requires either --from <profile> or --changeset <file>.');
+  }
+
+  // Drop deletes unless explicitly pruning.
+  if (!opts.prune) changes = changes.filter((c) => c.op !== 'delete');
+  if (opts.api) changes = changes.filter((c) => c.api === opts.api);
+
+  if (changes.length === 0) {
+    info('Nothing to deploy — target is already in sync.');
+    return result('Nothing to deploy.', {ok: true, to, applied: [], counts: empty()});
+  }
+
+  info(`Deploy to ${to}`);
+  for (const c of changes) {
+    const glyph = c.op === 'create' ? '+' : c.op === 'delete' ? '-' : '~';
+    info(`  ${glyph} ${c.api}/${c.entity}/${c.key}`);
+  }
+
+  // A dry-run only inspects local snapshots — no live credentials required.
+  if (opts.dryRun) {
+    info('\n--dry-run: no changes applied.');
+    return result('Dry run complete.', {ok: true, dryRun: true, to, planned: summarize(changes)});
+  }
+
+  const targetProfile = resolveProfile(to);
+
+  if (!opts.yes && !isJsonMode()) {
+    const confirmed = await confirm({
+      message: `Apply ${changes.length} change(s) to ${to}?`,
+      default: false,
+    });
+    if (!confirmed) {
+      info('Aborted.');
+      return result('Aborted.', {ok: false, aborted: true});
+    }
+  }
+
+  const applied = await applyChanges({targetProfile, to, changes});
+  const counts = applied.reduce(
+    (acc, a) => {
+      acc[a.ok ? a.op : 'failed']++;
+      return acc;
+    },
+    {...empty(), failed: 0}
+  );
+
+  info(`\nDone: +${counts.create} ~${counts.update} -${counts.delete}  (${counts.failed} failed)`);
+  if (counts.failed > 0) process.exitCode = 1;
+  return result('Deploy complete.', {ok: counts.failed === 0, to, counts, applied});
+};
+
+async function applyChanges({targetProfile, to, changes}) {
+  const clients = new Map(); // api -> got client
+  const getClient = async (api) => {
+    if (!clients.has(api)) clients.set(api, await apiClient(targetProfile, api));
+    return clients.get(api);
+  };
+
+  const tplCache = {map: null};   // dataTemplate name -> {id, locationCode}
+  const liveMaps = new Map();     // `${prefix}|${entity}` -> Map(naturalKey -> id)
+
+  // Apply in dependency order: creates/updates ascending (parents before
+  // children), deletes descending (children before parents). DO changes are
+  // independent of scheduler ordering and keep their original order.
+  const order = (c) => (c.api === 'scheduler' ? schedulerDeployOrder(c.entity) : 0);
+  const writes = changes.filter((c) => c.op !== 'delete').sort((a, b) => order(a) - order(b));
+  const deletes = changes.filter((c) => c.op === 'delete').sort((a, b) => order(b) - order(a));
+
+  // Group consecutive changes by api+entity+dataTemplate so each live
+  // collection is fetched once. Grouping preserves the dependency ordering.
+  const applied = [];
+  for (const group of groupChanges([...writes, ...deletes])) {
+    const {api, gk, meta, items} = group;
+    if (!meta) {
+      for (const c of items) applied.push({...ref(c), ok: false, error: `No routing metadata for ${gk}; re-import.`});
+      continue;
+    }
+
+    let ctx;
+    try {
+      const client = await getClient(api);
+      ctx = await resolveContext({client, api, meta, tplCache, liveMaps});
+    } catch (err) {
+      for (const c of items) applied.push({...ref(c), ok: false, error: err.message});
+      continue;
+    }
+
+    const client = await getClient(api);
+    const {collPath, desc, lookups, prefix, dataTemplateId} = ctx;
+
+    // Natural-key → id map (from live) for updates/deletes.
+    const needsLive = items.some((c) => c.op !== 'create');
+    const ownMap = needsLive
+      ? await liveKeyIdMap({client, api, collPath, desc, liveMaps, prefix, entity: meta.entity, dataTemplateId})
+      : new Map();
+
+    for (const c of items) {
+      try {
+        const body = desc ? resolveRefs(c.record, desc, lookups) : c.record;
+        if (c.op === 'create') {
+          await client.post(collPath, {json: body});
+        } else {
+          const id = ownMap.get(c.key);
+          if (id == null) throw new Error(`No live ${meta.entity} keyed "${c.key}" to ${c.op}.`);
+          if (c.op === 'update') await client.put(`${collPath}/${id}`, {json: body});
+          else await client.delete(`${collPath}/${id}`);
+        }
+        applied.push({...ref(c), ok: true});
+        info(`  ok ${c.op} ${gk}/${c.key}`);
+      } catch (err) {
+        applied.push({...ref(c), ok: false, error: err.message});
+        info(`  FAIL ${c.op} ${gk}/${c.key}: ${err.message}`);
+      }
+    }
+  }
+  return applied;
+}
+
+/** Group changes by api+entity+dataTemplate, preserving input (dependency) order. */
+function groupChanges(changes) {
+  const groups = new Map();
+  for (const c of changes) {
+    const gk = [c.api, c.entity, c.meta?.dataTemplate].filter(Boolean).join('/');
+    if (!groups.has(gk)) groups.set(gk, {api: c.api, gk, meta: null, items: []});
+    const g = groups.get(gk);
+    if (!g.meta && c.meta) g.meta = c.meta;
+    g.items.push(c);
+  }
+  return groups.values();
+}
+
+/**
+ * Resolve where and how a group of changes is written. For DO this is just the
+ * `microservice/endpoint` path. For scheduler it resolves the descriptor, the
+ * scope path (`{locationCode}/{dataTemplateId}/{endpoint}` for template-scoped
+ * entities, bare `{endpoint}` for global ones), and the live key→id lookup maps
+ * needed to resolve id references in the body.
+ */
+async function resolveContext({client, api, meta, tplCache, liveMaps}) {
+  if (api !== 'scheduler') {
+    return {collPath: `${meta.microservice}/${meta.endpoint}`, desc: null, lookups: new Map(), prefix: '', dataTemplateId: null};
+  }
+  const desc = getSchedulerEntity(meta.entity);
+  if (!desc) throw new Error(`Unknown scheduler entity "${meta.entity}"; re-import.`);
+
+  let prefix = '';
+  let dataTemplateId = null;
+  if (desc.scope === 'template') {
+    const tpl = await resolveTemplate(client, meta.dataTemplate, tplCache);
+    prefix = `${tpl.locationCode}/${tpl.id}`;
+    dataTemplateId = tpl.id;
+  }
+  const collPath = prefix ? `${prefix}/${desc.endpoint}` : desc.endpoint;
+
+  // Build a key→id map for every id-reference's target collection. Each lookup
+  // is scoped to its own entity: template-scoped refs share this template's
+  // path + dataTemplate filter; global refs (e.g. Location) are unscoped.
+  const lookups = new Map();
+  for (const r of idRefs(desc)) {
+    const lookDesc = getSchedulerEntity(r.lookupEntity);
+    if (!lookDesc) throw new Error(`${desc.entityName}.${r.field} references unknown entity ${r.lookupEntity}.`);
+    const global = lookDesc.scope === 'global';
+    const lookPrefix = global ? '' : prefix;
+    const lookPath = lookPrefix ? `${lookPrefix}/${lookDesc.endpoint}` : lookDesc.endpoint;
+    const map = await liveKeyIdMap({
+      client, api, collPath: lookPath, desc: lookDesc, liveMaps,
+      prefix: lookPrefix, entity: r.lookupEntity, dataTemplateId: global ? null : dataTemplateId,
+    });
+    lookups.set(r.lookupEntity, map);
+  }
+  return {collPath, desc, lookups, prefix, dataTemplateId};
+}
+
+/**
+ * Resolve a dataTemplate name (the stable cross-environment key) to the target's
+ * numeric id and location code — both needed to build the scheduler path.
+ */
+async function resolveTemplate(client, name, tplCache) {
+  if (!name) throw new Error('Scheduler change is missing its dataTemplate name; re-import.');
+  if (!tplCache.map) {
+    const data = await client.get('data-templates', {searchParams: {size: 10000}}).json();
+    const templates = Array.isArray(data) ? data : data?.content ?? [];
+    tplCache.map = new Map();
+    tplCache.live = null;
+    for (const t of templates) {
+      const entry = {id: t.id, locationCode: t.location?.code, name: t.name};
+      if (t.name != null) tplCache.map.set(String(t.name), entry);
+      // Remember the live template as a fallback for missing names.
+      if (t.isLive && tplCache.live == null) tplCache.live = entry;
+    }
+  }
+  let tpl = tplCache.map.get(String(name));
+  if (!tpl) {
+    // The named template doesn't exist on the target — fall back to the live
+    // one (mirrors the scheduler API's own "no dataTemplate → live" behaviour).
+    if (!tplCache.live) {
+      throw new Error(`Target has no dataTemplate named "${name}" and no live template to fall back to.`);
+    }
+    info(`  dataTemplate "${name}" not found on target; defaulting to the live template "${tplCache.live.name}".`);
+    tpl = tplCache.live;
+  }
+  if (tpl.locationCode == null) {
+    throw new Error(`Target dataTemplate "${tpl.name ?? name}" has no location code.`);
+  }
+  return tpl;
+}
+
+/**
+ * Build (and cache) a natural-key → id map from a live collection. Scheduler
+ * keys are computed with the entity descriptor (matching the snapshot keys) and
+ * request the `expand` relations those keys depend on; DO falls back to name/code.
+ */
+async function liveKeyIdMap({client, api, collPath, desc, liveMaps, prefix, entity, dataTemplateId}) {
+  const cacheKey = `${prefix}|${entity}`;
+  if (liveMaps.has(cacheKey)) return liveMaps.get(cacheKey);
+
+  const expand = api === 'scheduler' && desc ? expandParam(desc) : undefined;
+  const searchParams = {size: 10000, ...(expand ? {expand} : {})};
+  const data = await client.get(collPath, {searchParams}).json();
+  let records = Array.isArray(data) ? data : data?.content ?? [];
+  // Some leaf endpoints ignore the path scope; filter to this template so keys
+  // don't collide with identically-named records under other templates.
+  if (desc) records = scopeRows(records, desc, dataTemplateId);
+
+  const map = new Map();
+  for (const r of records) {
+    if (r?.id == null) continue;
+    const key = api === 'scheduler' && desc ? matchKey(r, desc) : r?.name ?? r?.code;
+    if (key != null) map.set(String(key), r.id);
+  }
+  liveMaps.set(cacheKey, map);
+  return map;
+}
+
+function ref(c) {
+  return {op: c.op, api: c.api, entity: c.entity, key: c.key};
+}
+
+function summarize(changes) {
+  return changes.map(ref);
+}
+
+function empty() {
+  return {create: 0, update: 0, delete: 0};
+}
+
+export default doDeploy;