@gotillit/tllt 0.3.0

package/docs/workflow.md

@@ -0,0 +1,86 @@
+# Workflow: import → diff → deploy
+
+The CLI manages configuration as files so you can review, edit, version, and
+promote it between environments.
+
+## 1. import — snapshot live config to files
+
+```bash
+tllt import --profile acme-prod
+```
+
+Writes to `./{profile}/{api}/{Entity}/...` in the **current directory** (override
+with `--dir <path>`), so the config can live in its own git repo. Volatile fields (`id`,
+`createdAt`, `updatedAt`) are stripped, so a content difference always reflects
+a real configuration change. Each leaf folder gets a `_meta.json` recording how
+to route writes (api, microservice, endpoint, and for scheduler the dataTemplate).
+
+### Snapshot layout
+
+```
+acme-prod/            # written into the current directory (or --dir)
+  do/
+    Asset/
+      _meta.json                 # routing: {api:"do", microservice:"core", endpoint:"assets", entity:"Asset"}
+      _schema.json               # distilled, agent-readable contract (see schemas.md)
+      _schema.source.json        # raw authoritative schema (DO dynamic-UI model)
+      Filler 1.json
+    ActivityTemplate/
+      Pre start check/
+        ActivityTemplateItem/
+          _meta.json             # nested entities carry their own meta
+          CostImpact.json
+  scheduler/
+    DataTemplate/
+      Line A.json
+    Line A/                      # scheduler config is nested per dataTemplate
+      Equipment/
+        _meta.json               # {api:"scheduler", endpoint:"equipment", entity:"Equipment", dataTemplate:"Line A"}
+        Filler.json
+```
+
+The **filename is the natural key** (the record's `name`, or a composite for
+some entities). This is what `diff`/`deploy` match on across environments.
+Sidecar files (any `_*.json`) are schema/routing metadata and are ignored by
+`diff`/`deploy`.
+
+## 2. diff — compute a changeset
+
+```bash
+tllt diff --from acme-stage --to acme-prod
+```
+
+Produces the changes needed to make `to` look like `from`:
+
+- **create** — in `from`, not in `to`
+- **update** — in both, content differs
+- **delete** — in `to`, not in `from`
+
+Entity/endpoint routing for each change is resolved from the nearest `_meta.json`,
+so nested entities are attributed correctly. Save with `--out plan.json`.
+
+## 3. deploy — apply the changeset
+
+```bash
+tllt deploy --from acme-stage --to acme-prod --dry-run   # preview
+tllt deploy --from acme-stage --to acme-prod --yes       # apply
+tllt deploy --changeset plan.json --to acme-prod --yes   # from a saved plan
+```
+
+- `create` → `POST` the record. `update` → `PUT /{id}`. `delete` → `DELETE /{id}`.
+- Target **ids are resolved by natural key**: deploy fetches the live collection
+  and matches on `name` (or `code`), since ids aren't in the snapshot.
+- **Deletes require `--prune`** so a partial snapshot can't wipe live config.
+- `--dry-run` needs no credentials (it only reads local snapshots).
+
+## Limitations to be aware of
+
+- Update/delete matching is by `name`/`code`. Entities whose natural key is a
+  **composite** (e.g. `ActivityAssignment`, some activity sub-entities) may not
+  resolve a live id for update/delete; create still works.
+- For **DO**, referential ordering isn't solved automatically — if a record
+  references another that doesn't exist yet on the target, that single change may
+  fail (reported in `applied[].error`); re-running after dependencies exist
+  resolves it. For **scheduler**, deploy applies changes in dependency order
+  (parents before children, deletes in reverse) and resolves references by natural
+  key, so ordering is handled within a single deploy.

package/import.js

@@ -0,0 +1,580 @@
+import fs from 'fs';
+import path from 'path';
+
+import {resolveProfile} from './lib/config.js';
+import {apiClient, fetchAsset} from './lib/client.js';
+import {getApi} from './lib/apis.js';
+import {distillSchema} from './lib/schema.js';
+import {info, result} from './lib/output.js';
+import {
+  SCHEDULER_ENTITIES,
+  expandParam,
+  toPortable,
+  matchKey,
+  scopeRows,
+} from './lib/scheduler-entities.js';
+
+// Re-exported so existing consumers (schema.js) keep importing it from here.
+export {SCHEDULER_ENTITIES};
+
+/**
+ * Where snapshots are written/read. Defaults to the current working directory
+ * (so config can live in its own git repo); override with --dir. Each profile
+ * is a subfolder: <baseDir>/<profile>/<api>/...
+ */
+export function resolveBaseDir(opts = {}) {
+  return opts.dir ? path.resolve(opts.dir) : process.cwd();
+}
+
+/**
+ * DO (Digital Operations) entities to snapshot. Schema-driven: the microservice
+ * and endpoint are read from the published entity schema, and many-to-one
+ * relationships are expanded so the snapshot is self-describing.
+ */
+export const DO_ENTITIES = [
+  // --- Asset model ---
+  {entityName: 'Asset', filter: {'active.equals': true}},
+  {entityName: 'AssetClass'},
+  {entityName: 'AssetProfile'},
+  {entityName: 'AssetStatusColor', fileNameField: (o) => o.status},
+  {
+    entityName: 'AssetAttribute',
+    folderName: 'asset',
+    parentFolder: 'Asset',
+    fileNameField: (o) => o.attribute?.name,
+  },
+  {
+    entityName: 'AssetTolerance',
+    folderName: 'asset',
+    parentFolder: 'Asset',
+    fileNameField: (o) => o.processVariable?.name,
+  },
+  {entityName: 'AssetMeterTemplate', folderName: 'asset', parentFolder: 'Asset'},
+
+  // --- Attributes & process variables ---
+  {entityName: 'Attribute'},
+  {entityName: 'AttributeGroup'},
+  {
+    entityName: 'AttributeGroupItem',
+    folderName: 'attributeGroup',
+    parentFolder: 'AttributeGroup',
+    fileNameField: (o) => o.attribute?.name,
+  },
+  {
+    entityName: 'AttributeGroupAssignment',
+    fileNameField: (o) =>
+      [
+        o.attributeGroup?.name,
+        o.asset?.name ?? o.material?.externalId ?? o.order?.orderNumber,
+      ]
+        .filter(Boolean)
+        .join(' - '),
+  },
+  {entityName: 'ProcessVariable'},
+  {entityName: 'UnitOfMeasure'},
+  {entityName: 'EventType'},
+
+  // --- Sites, calendars, shifts ---
+  {entityName: 'Site'},
+  {
+    entityName: 'SiteAttribute',
+    folderName: 'site',
+    parentFolder: 'Site',
+    fileNameField: (o) => o.attribute?.name,
+  },
+  {entityName: 'ShiftTemplate'},
+  {
+    entityName: 'ShiftTemplateItem',
+    folderName: 'shiftTemplate',
+    parentFolder: 'ShiftTemplate',
+    fileNameField: (o) => o.startTime,
+  },
+  {entityName: 'Calendar'},
+  {
+    entityName: 'CalendarItem',
+    folderName: 'calendar',
+    parentFolder: 'Calendar',
+    fileNameField: (o) =>
+      [o.shiftTemplate?.name, o.validFrom].filter(Boolean).join(' - '),
+  },
+
+  // --- Materials ---
+  {entityName: 'MaterialGroup'},
+  {entityName: 'MaterialProperty', fileNameField: (o) => o.externalId},
+  {entityName: 'Material', filter: {'active.equals': true}},
+  {
+    entityName: 'MaterialAttribute',
+    folderName: 'material',
+    parentFolder: 'Material',
+    fileNameField: (o) => o.attribute?.name,
+  },
+  {
+    entityName: 'MaterialComponent',
+    folderName: 'material',
+    parentFolder: 'Material',
+    fileNameField: (o) => o.component?.externalId ?? o.component?.name,
+  },
+  {
+    entityName: 'MaterialConversion',
+    folderName: 'material',
+    parentFolder: 'Material',
+    fileNameField: (o) => o.uom?.name,
+  },
+  {
+    entityName: 'MaterialTolerance',
+    folderName: 'material',
+    parentFolder: 'Material',
+    fileNameField: (o) => o.processVariable?.name,
+  },
+
+  // --- Inventory movements ---
+  {entityName: 'MovementType'},
+  {
+    entityName: 'MovementTypeField',
+    folderName: 'movementType',
+    parentFolder: 'MovementType',
+  },
+
+  // --- Alarms ---
+  {entityName: 'AlarmType', fileNameField: (o) => o.faultCode},
+  {
+    entityName: 'AlarmTypeAssignment',
+    folderName: 'alarmType',
+    parentFolder: 'AlarmType',
+    fileNameField: (o) => o.asset?.name,
+  },
+
+  // --- Edge & data sources ---
+  {entityName: 'DatasourceTemplate'},
+  {
+    entityName: 'DatasourceTemplateTag',
+    folderName: 'datasourceTemplate',
+    parentFolder: 'DatasourceTemplate',
+    fileNameField: (o) => o.processVariable?.name,
+  },
+  {
+    entityName: 'DatasourceTemplateTrigger',
+    fileNameField: (o) =>
+      [o.datasourceTemplateTag?.processVariable?.name, o.eventType?.name]
+        .filter(Boolean)
+        .join(' - '),
+  },
+  {
+    entityName: 'DatasourceTemplateAssignment',
+    folderName: 'datasourceTemplate',
+    parentFolder: 'DatasourceTemplate',
+    fileNameField: (o) => o.asset?.name ?? o.assetClass?.name,
+  },
+  {entityName: 'Edge'},
+  {entityName: 'EdgeDataSource', folderName: 'edge', parentFolder: 'Edge'},
+  {
+    entityName: 'EdgeDataTag',
+    fileNameField: (o) => [o.dataSource?.name, o.name].filter(Boolean).join(' - '),
+  },
+  {
+    entityName: 'EdgeTrigger',
+    fileNameField: (o) =>
+      [o.dataTag?.name, o.eventType?.name].filter(Boolean).join(' - '),
+  },
+
+  // --- Events ---
+  {
+    entityName: 'EventRelay',
+    fileNameField: (o) =>
+      [o.eventType?.name, o.fromAsset?.name ?? o.fromAssetClass?.name]
+        .filter(Boolean)
+        .join(' - '),
+  },
+  {entityName: 'EventSchedule'},
+
+  // --- Control parameters (manufacturing recipes) ---
+  {entityName: 'ControlParameter'},
+  {entityName: 'ControlParameterRecipe'},
+  {entityName: 'ControlParameterRule'},
+  {
+    entityName: 'ControlParameterRuleAttribute',
+    fileNameField: (o) =>
+      [o.controlParameterRule?.name, o.attribute?.name].filter(Boolean).join(' - '),
+  },
+
+  // --- Run rates ---
+  {
+    entityName: 'RunRateTemplate',
+    fileNameField: (o) =>
+      [
+        o.assetClass?.name ?? o.asset?.name,
+        o.material?.externalId ?? o.materialGroup?.name,
+      ]
+        .filter(Boolean)
+        .join(' - '),
+  },
+
+  // --- Order templates ---
+  {entityName: 'OrderStatus', fileNameField: (o) => o.status},
+  {entityName: 'OrderNumberAttribute', fileNameField: (o) => o.attribute?.name},
+  {entityName: 'OrderTemplate'},
+  {
+    entityName: 'OrderTemplateComponent',
+    folderName: 'orderTemplate',
+    parentFolder: 'OrderTemplate',
+    fileNameField: (o) => o.material?.externalId ?? o.materialGroup?.name,
+  },
+  {entityName: 'OrderTemplateDependency'},
+
+  // --- Activities ---
+  {entityName: 'ActivityClass'},
+  {entityName: 'ActivityItemOptionGroup', parentFolder: 'ActivityItemOptionGroup'},
+  {
+    entityName: 'ActivityItemOptionItem',
+    folderName: 'optionGroup',
+    parentFolder: 'ActivityItemOptionGroup',
+  },
+  {entityName: 'ActivityTemplate', filter: {'status.equals': 'LIVE'}},
+  {
+    entityName: 'ActivityTemplateItem',
+    fileNameField: (obj) => obj.itemKey,
+    folderName: 'activityTemplate',
+    parentFolder: 'ActivityTemplate',
+    filter: {'activityTemplate.status.equals': 'LIVE'},
+  },
+  {
+    entityName: 'ActivityStarter',
+    fileNameField: (obj) =>
+      obj.eventType.name +
+      (obj.activityKey != null ? ' - ' + obj.activityKey : '') +
+      (obj.targetAsset != null ? ' - ' + obj.targetAsset.name : ''),
+    folderName: 'template',
+    parentFolder: 'ActivityTemplate',
+    filter: {'template.status.equals': 'LIVE'},
+  },
+  {
+    entityName: 'ActivityAssignment',
+    folderName: 'template',
+    parentFolder: 'ActivityTemplate',
+    fileNameField: (obj) =>
+      [
+        ...(obj.site != null ? [obj.site.name] : []),
+        ...(obj.assetClass != null ? [obj.assetClass.name] : []),
+        ...(obj.asset != null ? [obj.asset.name] : []),
+        ...(obj.material != null ? [obj.material.externalId] : []),
+        ...(obj.materialGroup != null ? [obj.materialGroup.name] : []),
+        ...(obj.attribute != null ? [obj.attribute.name] : []),
+        ...(obj.attributeValue != null ? [obj.attributeValue] : []),
+        ...(obj.sourceAsset != null ? [obj.sourceAsset.name] : []),
+      ].join(' - '),
+    filter: {'template.status.equals': 'LIVE'},
+  },
+  {
+    entityName: 'ActivityProcessStarter',
+    fileNameField: (o) =>
+      [o.eventType?.name, o.activityKey].filter(Boolean).join(' - '),
+  },
+  {
+    entityName: 'ActivityProcessTrigger',
+    fileNameField: (o) => o.activityKey ?? o.triggerType,
+  },
+  {
+    entityName: 'ActivityAssignmentAttribute',
+    fileNameField: (o) => o.attribute?.name,
+  },
+];
+
+const STRIP_FIELDS = ['id', 'createdAt', 'updatedAt'];
+
+const doImport = async (opts = {}) => {
+  const profile = resolveProfile(opts.profile);
+  const onlyApi = opts.api; // optional: 'do' | 'scheduler'
+
+  const baseDir = resolveBaseDir(opts);
+  const baseFolder = path.join(baseDir, profile.name);
+  if (fs.existsSync(baseFolder)) {
+    fs.rmSync(baseFolder, {recursive: true, force: true});
+  }
+  createFolder(baseDir);
+  createFolder(baseFolder);
+
+  info(`Importing configuration for "${profile.name}" (${profile.baseUrl})`);
+
+  const summary = {profile: profile.name, baseUrl: profile.baseUrl, entities: []};
+
+  if (!onlyApi || onlyApi === 'do') {
+    await importApi('do', async (client) => {
+      for (const entity of DO_ENTITIES) {
+        const count = await importDoEntity({profile, client, entity, baseFolder});
+        summary.entities.push({api: 'do', entity: entity.entityName, count});
+      }
+    });
+  }
+
+  if (!onlyApi || onlyApi === 'scheduler') {
+    await importApi('scheduler', async (client) => {
+      const results = await importScheduler({profile, client, baseFolder});
+      summary.entities.push(...results);
+    });
+  }
+
+  // Build the client for an API and run its import block. If the client can't
+  // be built (e.g. an auth method the API doesn't accept), skip it with a
+  // warning rather than aborting the whole import.
+  async function importApi(apiId, block) {
+    let client;
+    try {
+      client = await apiClient(profile, apiId);
+    } catch (err) {
+      info(`  ${apiId}: skipped (${err.message})`);
+      summary.skipped = summary.skipped || [];
+      summary.skipped.push({api: apiId, reason: err.message});
+      return;
+    }
+    await block(client);
+  }
+
+  const total = summary.entities.reduce((n, e) => n + (e.count || 0), 0);
+  info(`\nImported ${total} records into ${baseFolder}`);
+  result(`Imported ${total} records for "${profile.name}".`, {ok: true, ...summary, path: baseFolder});
+};
+
+async function importDoEntity({profile, client, entity, baseFolder}) {
+  const {entityName} = entity;
+  const api = getApi('do');
+  try {
+    const schema = await fetchAsset(profile, 'do', `${api.schemaPath}/${entityName}.json`);
+    const expand = (schema.relationships || [])
+      .filter((a) => a.relationshipType === 'many-to-one')
+      .map((a) => a.relationshipName)
+      .join(',');
+
+    const data = await client
+      .get(`${schema.microserviceName}/${schema.endpoint}`, {
+        searchParams: {expand, size: 10000, ...(entity.filter || {})},
+      })
+      .json();
+
+    const meta = {
+      api: 'do',
+      microservice: schema.microserviceName,
+      endpoint: schema.endpoint,
+      entity: entityName,
+    };
+    const distilled = distillSchema(schema, 'do');
+    const entityFolder = writeEntityMeta(baseFolder, 'do', entityName, meta, distilled, schema);
+
+    let count = 0;
+    for (const obj of data) {
+      writeRecord({obj, entity, entityName, entityFolder, baseFolder, api: 'do', meta, schema: distilled});
+      count++;
+    }
+    info(`  do/${entityName}: ${count}`);
+    return count;
+  } catch (error) {
+    info(`  do/${entityName}: skipped (${error.message})`);
+    return 0;
+  }
+}
+
+/**
+ * Scheduler config is reached through the normalized REST surface. Global
+ * entities (Location, DataTemplate, OptimisationProfile) live at
+ * /api/scheduler/{endpoint}; everything else is partitioned per DataTemplate and
+ * addressed by path: /api/scheduler/{locationCode}/{dataTemplateId}/{endpoint}.
+ * The dataTemplate id and locationCode are environment-specific, so snapshots
+ * nest under scheduler/{templateName}/{Entity}/ and record the template *name*
+ * (the stable cross-environment key) in meta. The published schema is
+ * authoritative for these write shapes (unlike the deprecated flattened gateway).
+ */
+async function importScheduler({profile, client, baseFolder}) {
+  const results = [];
+  const api = getApi('scheduler');
+
+  // Fetch + distill each entity's live schema once (reused across templates).
+  const schemaCache = new Map();
+  const getSchema = async (entityName) => {
+    if (schemaCache.has(entityName)) return schemaCache.get(entityName);
+    let val = null;
+    try {
+      const raw = await fetchAsset(profile, 'scheduler', `${api.schemaPath}/${entityName}.json`);
+      val = {distilled: distillSchema(raw, 'scheduler'), raw};
+    } catch {
+      val = null; // schema is best-effort; import still proceeds without it
+    }
+    schemaCache.set(entityName, val);
+    return val;
+  };
+
+  // The data templates drive the per-template loop and the scope path.
+  let templates;
+  try {
+    const data = await client.get('data-templates', {searchParams: {size: 10000}}).json();
+    templates = Array.isArray(data) ? data : data?.content ?? [];
+  } catch (error) {
+    info(`  scheduler: skipped (${error.message})`);
+    return [{api: 'scheduler', entity: 'DataTemplate', count: 0, error: error.message}];
+  }
+
+  // Global entities first (no scope prefix). DataTemplate reuses the list above.
+  for (const desc of SCHEDULER_ENTITIES.filter((d) => d.scope === 'global')) {
+    const records = desc.entityName === 'DataTemplate' ? templates : null;
+    const count = await importSchedulerCollection({
+      client, desc, prefix: '', dataTemplate: null, records, baseFolder, getSchema,
+    });
+    results.push({api: 'scheduler', entity: desc.entityName, count});
+  }
+
+  // Per-template scoped entities, addressed by {locationCode}/{dataTemplateId}.
+  for (const tpl of templates) {
+    const tplName = cleanFileName(String(tpl.name ?? `template-${tpl.id}`));
+    const locationCode = tpl.location?.code;
+    if (locationCode == null) {
+      info(`  scheduler/${tplName}: skipped (template has no location)`);
+      continue;
+    }
+    const prefix = `${locationCode}/${tpl.id}`;
+    for (const desc of SCHEDULER_ENTITIES.filter((d) => d.scope === 'template')) {
+      const count = await importSchedulerCollection({
+        client, desc, prefix, dataTemplate: tplName, dataTemplateId: tpl.id, records: null, baseFolder, getSchema,
+      });
+      results.push({api: 'scheduler', dataTemplate: tplName, entity: desc.entityName, count});
+    }
+  }
+  return results;
+}
+
+/**
+ * Snapshot one scheduler collection (global or template-scoped). Records are
+ * reduced to portable form (volatile ids stripped, references collapsed to their
+ * natural keys) and keyed by their natural key — which is now stable, so
+ * diff/deploy can match them for update/delete instead of create-only.
+ */
+async function importSchedulerCollection({client, desc, prefix, dataTemplate, dataTemplateId, records, baseFolder, getSchema}) {
+  const {entityName, endpoint} = desc;
+  const label = dataTemplate ? `scheduler/${dataTemplate}/${entityName}` : `scheduler/${entityName}`;
+  try {
+    let data = records;
+    if (!data) {
+      const expand = expandParam(desc);
+      const searchParams = {size: 10000, ...(expand ? {expand} : {})};
+      const url = prefix ? `${prefix}/${endpoint}` : endpoint;
+      data = await client.get(url, {searchParams}).json();
+    }
+    let rows = Array.isArray(data) ? data : data?.content ?? [];
+    // Some leaf endpoints ignore the path scope; filter to this template.
+    rows = scopeRows(rows, desc, dataTemplateId);
+
+    const folder = dataTemplate
+      ? path.join(baseFolder, 'scheduler', dataTemplate, entityName)
+      : path.join(baseFolder, 'scheduler', entityName);
+    createFolder(path.dirname(folder));
+    createFolder(folder);
+
+    const meta = {
+      api: 'scheduler',
+      entity: entityName,
+      endpoint,
+      scope: desc.scope,
+      ...(dataTemplate ? {dataTemplate} : {}),
+    };
+    fs.writeFileSync(path.join(folder, '_meta.json'), JSON.stringify(meta, null, 2));
+    const schema = await getSchema(entityName);
+    if (schema?.distilled) {
+      fs.writeFileSync(path.join(folder, '_schema.json'), JSON.stringify(schema.distilled, null, 2));
+    }
+    if (schema?.raw) {
+      fs.writeFileSync(path.join(folder, '_schema.source.json'), JSON.stringify(schema.raw, null, 2));
+    }
+
+    let count = 0;
+    const used = new Set();
+    for (const obj of rows) {
+      let fileName = matchKey(obj, desc) || `record-${count}`;
+      if (used.has(fileName)) fileName = `${fileName}~${count}`; // guard rare collisions
+      used.add(fileName);
+      fs.writeFileSync(path.join(folder, `${fileName}.json`), JSON.stringify(toPortable(obj, desc), null, 2));
+      count++;
+    }
+    info(`  ${label}: ${count}`);
+    return count;
+  } catch (error) {
+    info(`  ${label}: skipped (${error.message})`);
+    return 0;
+  }
+}
+
+/** Resolve the target folder for a record and write it as cleaned JSON. */
+function writeRecord({obj, entity, entityName, entityFolder, baseFolder, api, meta, schema}) {
+  const rawFileName = entity.fileNameField != null ? entity.fileNameField(obj) : obj.name;
+  const fileName = cleanFileName(String(rawFileName ?? 'unnamed'));
+
+  let targetFolder = entityFolder;
+  const apiRoot = path.join(baseFolder, api);
+  if (entity.folderName) {
+    const folder = cleanFileName(obj[entity.folderName].name);
+    targetFolder = path.join(apiRoot, entity.parentFolder, folder, entityName);
+    createFolder(path.join(apiRoot, entity.parentFolder));
+    createFolder(path.join(apiRoot, entity.parentFolder, folder));
+    createFolder(targetFolder);
+    delete obj[entity.folderName];
+  } else if (entity.parentFolder) {
+    const folder = cleanFileName(obj.name);
+    targetFolder = path.join(apiRoot, entity.parentFolder, folder);
+    createFolder(path.join(apiRoot, entity.parentFolder));
+    createFolder(targetFolder);
+  }
+
+  // Drop routing (_meta.json) and contract (_schema.json) sidecars into the
+  // leaf folder (once) so diff/deploy and agents can resolve them from the
+  // nearest sidecar, regardless of nesting.
+  if (meta) {
+    const leafMeta = path.join(targetFolder, '_meta.json');
+    if (!fs.existsSync(leafMeta)) fs.writeFileSync(leafMeta, JSON.stringify(meta, null, 2));
+  }
+  if (schema) {
+    const leafSchema = path.join(targetFolder, '_schema.json');
+    if (!fs.existsSync(leafSchema)) fs.writeFileSync(leafSchema, JSON.stringify(schema, null, 2));
+  }
+
+  const filePath = path.join(targetFolder, `${fileName}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(stripVolatile(obj), null, 2));
+}
+
+/**
+ * Create the api/entity folder and write its sidecars:
+ *   _meta.json          routing (api, microservice, endpoint, dataTemplate)
+ *   _schema.json        distilled, agent-readable contract for the entity
+ *   _schema.source.json the raw authoritative schema (DO: the same
+ *                       /assets/data/schema/{Entity}.json that drives the
+ *                       dynamic UI), kept for completeness
+ */
+function writeEntityMeta(baseFolder, api, entityName, meta, schema, rawSchema) {
+  const folder = path.join(baseFolder, api, entityName);
+  createFolder(path.join(baseFolder, api));
+  createFolder(folder);
+  fs.writeFileSync(path.join(folder, '_meta.json'), JSON.stringify(meta, null, 2));
+  if (schema) fs.writeFileSync(path.join(folder, '_schema.json'), JSON.stringify(schema, null, 2));
+  if (rawSchema) {
+    fs.writeFileSync(path.join(folder, '_schema.source.json'), JSON.stringify(rawSchema, null, 2));
+  }
+  return folder;
+}
+
+function stripVolatile(obj) {
+  if (Array.isArray(obj)) return obj.map(stripVolatile);
+  if (obj && typeof obj === 'object') {
+    const out = {};
+    for (const key of Object.keys(obj)) {
+      if (STRIP_FIELDS.includes(key)) continue;
+      out[key] = stripVolatile(obj[key]);
+    }
+    return out;
+  }
+  return obj;
+}
+
+function createFolder(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, {recursive: true});
+}
+
+function cleanFileName(raw) {
+  return raw.replace(/[<>:"/\\|?*]/g, '');
+}
+
+export default doImport;

package/lib/apis.js

@@ -0,0 +1,39 @@
+/**
+ * Registry of the TilliT API surfaces the CLI talks to.
+ *
+ * Both are served from the per-tenant subdomain (https://{tenant}.tillit.cloud)
+ * under the shared /api gateway prefix, and accept the same auth (basic or
+ * api-key/bearer) plus the tillit-tenant header.
+ *
+ *  - do        Digital Operations REST API (microservices: core, activity,
+ *              tenant, edge, user-settings, report, cube). Prefix /api.
+ *  - scheduler Scheduler REST API. Prefix /api/scheduler. Config is partitioned
+ *              per dataTemplate (the bare /scheduler path is the web app).
+ */
+export const APIS = {
+  do: {
+    id: 'do',
+    label: 'Digital Operations API',
+    prefix: '/api',
+    // Where the entity JSON schemas are published for schema-driven import.
+    schemaPath: '/assets/data/schema',
+  },
+  scheduler: {
+    id: 'scheduler',
+    label: 'Scheduler API',
+    // Served under the shared /api gateway prefix (the /scheduler path is the
+    // Bryntum web app, not the API).
+    prefix: '/api/scheduler',
+    // Entity schemas are published live, same format as DO, under a
+    // scheduler/ subfolder.
+    schemaPath: '/assets/data/schema/scheduler',
+  },
+};
+
+export function getApi(id) {
+  const api = APIS[id];
+  if (!api) {
+    throw new Error(`Unknown API "${id}". Known APIs: ${Object.keys(APIS).join(', ')}`);
+  }
+  return api;
+}