@dcupl/cli 1.4.0-beta.0 → 1.4.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/README.md +45 -0
  2. package/dist/cli.js +136 -18
  3. package/dist/cli.js.map +1 -1
  4. package/dist/functions/app/commands/fn/_fn-helpers.d.ts +13 -0
  5. package/dist/functions/app/commands/fn/_fn-helpers.js +56 -0
  6. package/dist/functions/app/commands/fn/_fn-helpers.js.map +1 -1
  7. package/dist/functions/app/commands/fn/aggregate.d.ts +8 -1
  8. package/dist/functions/app/commands/fn/aggregate.js +29 -3
  9. package/dist/functions/app/commands/fn/aggregate.js.map +1 -1
  10. package/dist/functions/app/commands/fn/facets.d.ts +1 -0
  11. package/dist/functions/app/commands/fn/facets.js +2 -0
  12. package/dist/functions/app/commands/fn/facets.js.map +1 -1
  13. package/dist/functions/app/commands/fn/group-by.d.ts +6 -0
  14. package/dist/functions/app/commands/fn/group-by.js +13 -22
  15. package/dist/functions/app/commands/fn/group-by.js.map +1 -1
  16. package/dist/functions/app/commands/fn/pivot.d.ts +14 -0
  17. package/dist/functions/app/commands/fn/pivot.js +72 -0
  18. package/dist/functions/app/commands/fn/pivot.js.map +1 -0
  19. package/dist/functions/app/commands/fn/suggest.d.ts +17 -0
  20. package/dist/functions/app/commands/fn/suggest.js +34 -0
  21. package/dist/functions/app/commands/fn/suggest.js.map +1 -0
  22. package/dist/functions/app/commands/resolve-source.js +13 -5
  23. package/dist/functions/app/commands/resolve-source.js.map +1 -1
  24. package/dist/functions/app/commands/validate.js +1 -4
  25. package/dist/functions/app/commands/validate.js.map +1 -1
  26. package/dist/functions/app/daemon/controllers/fn.controller.d.ts +8 -0
  27. package/dist/functions/app/daemon/controllers/fn.controller.js +20 -0
  28. package/dist/functions/app/daemon/controllers/fn.controller.js.map +1 -1
  29. package/dist/functions/app/daemon/services/attribute-validation.d.ts +21 -0
  30. package/dist/functions/app/daemon/services/attribute-validation.js +161 -0
  31. package/dist/functions/app/daemon/services/attribute-validation.js.map +1 -0
  32. package/dist/functions/app/daemon/services/dcupl-host.service.d.ts +7 -0
  33. package/dist/functions/app/daemon/services/dcupl-host.service.js +87 -6
  34. package/dist/functions/app/daemon/services/dcupl-host.service.js.map +1 -1
  35. package/dist/functions/app/e2e/port-lock.d.ts +8 -0
  36. package/dist/functions/app/e2e/port-lock.js +50 -0
  37. package/dist/functions/app/e2e/port-lock.js.map +1 -1
  38. package/dist/functions/config/commands/get.d.ts +3 -3
  39. package/dist/functions/config/commands/get.js +34 -16
  40. package/dist/functions/config/commands/get.js.map +1 -1
  41. package/dist/functions/config/commands/set.js +7 -2
  42. package/dist/functions/config/commands/set.js.map +1 -1
  43. package/dist/functions/config/io.d.ts +4 -1
  44. package/dist/functions/config/io.js +43 -8
  45. package/dist/functions/config/io.js.map +1 -1
  46. package/dist/functions/files/commands/copy.js +1 -1
  47. package/dist/functions/files/commands/copy.js.map +1 -1
  48. package/dist/functions/files/commands/delete.js +1 -1
  49. package/dist/functions/files/commands/delete.js.map +1 -1
  50. package/dist/functions/files/commands/list.js +6 -3
  51. package/dist/functions/files/commands/list.js.map +1 -1
  52. package/dist/functions/files/commands/move.js +1 -1
  53. package/dist/functions/files/commands/move.js.map +1 -1
  54. package/dist/functions/files/commands/pull.d.ts +14 -1
  55. package/dist/functions/files/commands/pull.js +110 -1
  56. package/dist/functions/files/commands/pull.js.map +1 -1
  57. package/dist/functions/files/commands/push.js +5 -3
  58. package/dist/functions/files/commands/push.js.map +1 -1
  59. package/dist/functions/files/commands/read.js +1 -1
  60. package/dist/functions/files/commands/read.js.map +1 -1
  61. package/dist/functions/files/commands/render.d.ts +29 -0
  62. package/dist/functions/files/commands/render.js +8 -4
  63. package/dist/functions/files/commands/render.js.map +1 -1
  64. package/dist/functions/files/commands/status.js +1 -0
  65. package/dist/functions/files/commands/status.js.map +1 -1
  66. package/dist/functions/files/commands/versions/copy.js +1 -1
  67. package/dist/functions/files/commands/versions/copy.js.map +1 -1
  68. package/dist/functions/files/commands/versions/delete.js +1 -1
  69. package/dist/functions/files/commands/versions/delete.js.map +1 -1
  70. package/dist/functions/files/commands/versions/list.js +4 -0
  71. package/dist/functions/files/commands/versions/list.js.map +1 -1
  72. package/dist/functions/files/commands/write.js +1 -1
  73. package/dist/functions/files/commands/write.js.map +1 -1
  74. package/dist/functions/files/files-pull.js +10 -7
  75. package/dist/functions/files/files-pull.js.map +1 -1
  76. package/dist/functions/files/files-push.js +11 -8
  77. package/dist/functions/files/files-push.js.map +1 -1
  78. package/dist/functions/files/test-helpers.d.ts +11 -0
  79. package/dist/functions/files/test-helpers.js +28 -0
  80. package/dist/functions/files/test-helpers.js.map +1 -1
  81. package/dist/functions/generate/files/generate-code.d.ts +1 -1
  82. package/dist/functions/generate/files/generate-files.d.ts +7 -1
  83. package/dist/functions/generate/files/generate-files.js +63 -15
  84. package/dist/functions/generate/files/generate-files.js.map +1 -1
  85. package/dist/functions/generate/files/workflow-presets.d.ts +6 -0
  86. package/dist/functions/generate/files/workflow-presets.js +158 -0
  87. package/dist/functions/generate/files/workflow-presets.js.map +1 -0
  88. package/dist/functions/generate/model-from-data/generate-model-from-data.js +4 -3
  89. package/dist/functions/generate/model-from-data/generate-model-from-data.js.map +1 -1
  90. package/dist/functions/generate/model-from-data/infer-to-model.js +5 -1
  91. package/dist/functions/generate/model-from-data/infer-to-model.js.map +1 -1
  92. package/dist/functions/generate/projects/generate-project.d.ts +5 -0
  93. package/dist/functions/generate/projects/generate-project.js +20 -6
  94. package/dist/functions/generate/projects/generate-project.js.map +1 -1
  95. package/dist/functions/helper/api-client.js +9 -14
  96. package/dist/functions/helper/api-client.js.map +1 -1
  97. package/dist/functions/helper/credentials.helper.d.ts +21 -0
  98. package/dist/functions/helper/credentials.helper.js +39 -0
  99. package/dist/functions/helper/credentials.helper.js.map +1 -0
  100. package/dist/functions/helper/load-env.d.ts +1 -0
  101. package/dist/functions/helper/load-env.js +10 -0
  102. package/dist/functions/helper/load-env.js.map +1 -0
  103. package/dist/functions/helper/output.d.ts +1 -1
  104. package/dist/functions/helper/output.js +7 -11
  105. package/dist/functions/helper/output.js.map +1 -1
  106. package/dist/functions/schemas/examples/AttributeQualityConfig.example.json +10 -0
  107. package/dist/functions/schemas/examples/ModelDefinition.example.json +21 -2
  108. package/dist/functions/schemas/examples/ScriptStepConfig.example.json +1 -1
  109. package/dist/functions/schemas/registry.d.ts +14 -0
  110. package/dist/functions/schemas/registry.js +40 -0
  111. package/dist/functions/schemas/registry.js.map +1 -1
  112. package/dist/functions/schemas/validate.d.ts +22 -0
  113. package/dist/functions/schemas/validate.js +67 -0
  114. package/dist/functions/schemas/validate.js.map +1 -0
  115. package/dist/functions/serve/main.js +6 -5
  116. package/dist/functions/serve/main.js.map +1 -1
  117. package/dist/functions/version/command.d.ts +12 -1
  118. package/dist/functions/version/command.js +54 -1
  119. package/dist/functions/version/command.js.map +1 -1
  120. package/dist/functions/workflow/commands/deploy.d.ts +8 -1
  121. package/dist/functions/workflow/commands/deploy.js +24 -0
  122. package/dist/functions/workflow/commands/deploy.js.map +1 -1
  123. package/dist/functions/workflow/commands/run.d.ts +26 -0
  124. package/dist/functions/workflow/commands/run.js +85 -0
  125. package/dist/functions/workflow/commands/run.js.map +1 -0
  126. package/dist/functions/workflow/commands/runners.d.ts +2 -0
  127. package/dist/functions/workflow/commands/runners.js +10 -1
  128. package/dist/functions/workflow/commands/runners.js.map +1 -1
  129. package/dist/functions/workflow/commands/test.d.ts +3 -0
  130. package/dist/functions/workflow/commands/test.js +8 -64
  131. package/dist/functions/workflow/commands/test.js.map +1 -1
  132. package/dist/functions/workflow/commands/trace.d.ts +4 -2
  133. package/dist/functions/workflow/commands/trace.js +22 -1
  134. package/dist/functions/workflow/commands/trace.js.map +1 -1
  135. package/dist/functions/workflow/commands/validate.js +8 -1
  136. package/dist/functions/workflow/commands/validate.js.map +1 -1
  137. package/dist/functions/workflow/run-failure.d.ts +11 -0
  138. package/dist/functions/workflow/run-failure.js +74 -0
  139. package/dist/functions/workflow/run-failure.js.map +1 -0
  140. package/dist/functions/workflow/runner-health.d.ts +16 -0
  141. package/dist/functions/workflow/runner-health.js +36 -0
  142. package/dist/functions/workflow/runner-health.js.map +1 -0
  143. package/dist/functions/workflow/script-lint.d.ts +10 -0
  144. package/dist/functions/workflow/script-lint.js +488 -0
  145. package/dist/functions/workflow/script-lint.js.map +1 -0
  146. package/dist/functions/workflow/template-io.js +1 -1
  147. package/dist/functions/workflow/template-io.js.map +1 -1
  148. package/dist/functions/workflow/validate.js +4 -1
  149. package/dist/functions/workflow/validate.js.map +1 -1
  150. package/dist/index.js +6 -3
  151. package/dist/index.js.map +1 -1
  152. package/files/common/.env.example +4 -0
  153. package/files/common/_gitignore +3 -1
  154. package/package.json +35 -37
package/README.md CHANGED
@@ -47,10 +47,55 @@ Add this to your project's `.gitignore`:
47
47
 
48
48
  Pushing directly to `production` is rejected. Push to a named version, then promote with the existing copy-version flow.
49
49
 
50
+ ### JSON output (`--json`)
51
+
52
+ Every `files` subcommand run with `--json` emits exactly one JSON object on stdout, and every result carries a `success` boolean, so a scripted caller can branch on `.success` across all verbs. `.success` and the exit code always agree:
53
+
54
+ | Outcome | `success` | Exit code | Shape |
55
+ |---------|-----------|-----------|-------|
56
+ | Full success | `true` | 0 | the verb's payload (see table below) |
57
+ | Partial failure (`push`/`pull` only: a transfer failed or could not be verified) | `false` | 2 | the verb's payload — inspect `failed` / `unverified`; no `error`/`code` keys |
58
+ | Hard error (any verb) | `false` | 1 | `{ "success": false, "error": "<message>", "code": "<CODE>", ... }` |
59
+
60
+ Warnings and progress notices go to stderr, so stdout always stays a single parseable object.
61
+
62
+ Guaranteed keys per verb (additional keys may appear):
63
+
64
+ | Verb | Keys |
65
+ |------|------|
66
+ | `status` | `success` (always `true` — status is a report), `versionId`, `hasBaseline`, `uploads`, `downloads`, `conflicts`, `wouldDeleteOnServerInStrictMode`, `wouldDeleteLocallyInStrictMode`, `unchanged` |
67
+ | `push` | `success` (`false` on partial failure, exit 2), `versionId`, `uploaded`, `deleted`, `failed`, `conflicts`, `resolvedConflicts`, `unchanged`, `unverified` |
68
+ | `pull` | `success` (`false` on partial failure, exit 2), `versionId`, `downloaded`, `deletedLocally`, `failed`, `switched`, `unchanged`, `unverified` |
69
+ | `list` | `success`, `paths` |
70
+ | `read` | `success`, `path`, `content` |
71
+ | `write` | `success`, `path`, `bytes`, `version` |
72
+ | `copy` | `success`, `from`, `to`, `version` |
73
+ | `move` | `success`, `from`, `to`, `version` |
74
+ | `delete` | `success`, `path`, `version` |
75
+ | `create-folder` | `success`, `path` |
76
+ | `versions list` | `success`, `versions` |
77
+ | `versions copy` | `success`, `from`, `to` |
78
+ | `versions delete` | `success`, `id` |
79
+
80
+ `--dry-run` results use the same shape as the real operation.
81
+
50
82
  ### Legacy commands
51
83
 
52
84
  `dcupl files:push` and `dcupl files:pull` (with the colon syntax) are the original zip-based commands. They keep their existing behavior unchanged. Prefer the new `dcupl files <subcommand>` commands for new workflows.
53
85
 
86
+ Note: the deprecated `dcupl files:versions` alias delegates to `dcupl files versions list`, so its `--json` output uses the same `{ success, versions }` envelope documented above.
87
+
88
+ ## Credentials
89
+
90
+ Provide `apiKey` / `projectId` via (highest priority first):
91
+
92
+ 1. CLI flags `--api-key` / `--project-id`
93
+ 2. Env vars `DCUPL_API_KEY` / `DCUPL_PROJECT_ID`
94
+ 3. A workspace `.env` (auto-loaded; real env vars override it)
95
+ 4. `dcupl.secrets.json` (apiKey) and `dcupl.config.json` (projectId)
96
+
97
+ `dcupl config set` writes to `dcupl.secrets.json` if present, else to `.env`.
98
+
54
99
  ## CLI Lifecycle Contract
55
100
 
56
101
  The dcupl CLI mirrors the dcupl SDK's declarative model: the SDK separates
package/dist/cli.js CHANGED
@@ -7,6 +7,7 @@ const api_client_1 = require("./functions/helper/api-client");
7
7
  const output_1 = require("./functions/helper/output");
8
8
  const parse_fail_1 = require("./functions/helper/parse-fail");
9
9
  const command_js_1 = require("./functions/schemas/command.js");
10
+ const workflow_presets_js_1 = require("./functions/generate/files/workflow-presets.js");
10
11
  const command_js_2 = require("./functions/version/command.js");
11
12
  const init_options_js_1 = require("./functions/app/daemon/services/init-options.js");
12
13
  function parseAutoServePort(raw) {
@@ -53,7 +54,7 @@ function buildCli(rawArgs) {
53
54
  })
54
55
  .option('project-id', {
55
56
  type: 'string',
56
- describe: 'Console project ID (required with --starter existing)',
57
+ describe: 'Console project ID (implies --starter existing when --starter is omitted)',
57
58
  })
58
59
  .option('api-key', {
59
60
  type: 'string',
@@ -122,11 +123,13 @@ function buildCli(rawArgs) {
122
123
  'test-setup',
123
124
  'test',
124
125
  'test-config',
126
+ 'workflow',
125
127
  ],
126
128
  })
127
- .option('name', { describe: 'Name for model generation', type: 'string' })
129
+ .option('name', { describe: 'Name for model generation, or the workflow key for `generate workflow`', type: 'string' })
128
130
  .option('file-name', { describe: 'File name for generation', type: 'string' })
129
131
  .option('operator', { describe: 'Operator name for operator generation', type: 'string' })
132
+ .option('template', { describe: `Workflow preset (used by \`generate workflow\`, default: ${workflow_presets_js_1.WORKFLOW_PRESETS[0]})`, type: 'string', choices: workflow_presets_js_1.WORKFLOW_PRESETS })
130
133
  .option('title', { describe: 'Test title (used by `generate test`)', type: 'string' })
131
134
  .option('from', { describe: 'Data file (CSV/JSON/NDJSON) to infer a model from', type: 'string' })
132
135
  .option('register', { describe: 'Register the generated model + data resource in dcupl.lc.json', type: 'boolean' })
@@ -148,6 +151,20 @@ function buildCli(rawArgs) {
148
151
  .option('example', { type: 'boolean', default: false, describe: 'Append a curated example payload' }), (argv) => {
149
152
  const output = (0, output_1.createOutput)(argv.json);
150
153
  (0, command_js_1.schemasGetCommand)({ name: argv.name, json: argv.json, example: argv.example }, output);
154
+ })
155
+ .command('validate <file>', 'Validate a JSON file against a registry schema (Zod-kind, e.g. TemplateV3)', (args) => args
156
+ .positional('file', { type: 'string', describe: 'Path to the JSON file to validate', demandOption: true })
157
+ .option('against', { type: 'string', demandOption: true, describe: 'Schema name to validate against (see `dcupl schemas list` — [Zod] entries only)' }), async (argv) => {
158
+ const output = (0, output_1.createOutput)(argv.json);
159
+ try {
160
+ const { schemasValidateCommand } = await import('./functions/schemas/validate.js');
161
+ const valid = await schemasValidateCommand({ file: argv.file, against: argv.against, json: argv.json }, output);
162
+ if (!valid)
163
+ process.exitCode = 1;
164
+ }
165
+ catch (err) {
166
+ output.error(err.message, err.code || 'SCHEMA_VALIDATE_FAILED');
167
+ }
151
168
  })
152
169
  .demandCommand(1);
153
170
  }, () => { })
@@ -228,20 +245,21 @@ function buildCli(rawArgs) {
228
245
  })
229
246
  .command('trace', 'Show the node-by-node execution state of a single run (debug a workflow run).', (a) => a
230
247
  .option('id', { type: 'string', demandOption: true, describe: 'Deployed workflow uid' })
231
- .option('run', { type: 'string', demandOption: true, describe: 'Execution runId (from `workflow history`)' }), async (argv) => {
248
+ .option('run', { type: 'string', describe: 'Execution runId (from `workflow history`)' })
249
+ .option('last', { type: 'boolean', default: false, describe: 'Trace the most recent run instead of naming one with --run' }), async (argv) => {
232
250
  const { traceCommand } = await import('./functions/workflow/commands/trace.js');
233
251
  const { createApiClient: mkClient } = await import('./functions/helper/api-client.js');
234
252
  const output = (0, output_1.createOutput)(!!argv.json);
235
253
  try {
236
- await traceCommand(output, mkClient(), { id: argv.id, run: argv.run });
254
+ await traceCommand(output, mkClient(), { id: argv.id, run: argv.run, last: !!argv.last });
237
255
  }
238
256
  catch (err) {
239
257
  output.error(err.message, err.code || 'WORKFLOW_TRACE_FAILED');
240
258
  }
241
259
  })
242
- .command('runners <subcommand>', 'Inspect the runners available to this project.', (rr) => {
260
+ .command('runners [subcommand]', 'Inspect the runners available to this project.', (rr) => {
243
261
  return rr
244
- .command('list', 'List the runners available to this project (uid / key / type / url).', () => { }, async (argv) => {
262
+ .command(['list', '$0'], 'List the runners available to this project (uid / key / type / url / health).', () => { }, async (argv) => {
245
263
  const { runnersCommand } = await import('./functions/workflow/commands/runners.js');
246
264
  const { createApiClient: mkClient } = await import('./functions/helper/api-client.js');
247
265
  const output = (0, output_1.createOutput)(!!argv.json);
@@ -262,8 +280,7 @@ function buildCli(rawArgs) {
262
280
  catch (err) {
263
281
  output.error(err.message, err.code || 'WORKFLOW_RUNNERS_GET_FAILED');
264
282
  }
265
- })
266
- .demandCommand(1);
283
+ });
267
284
  }, () => { })
268
285
  .command('test', 'Deploy to a (dev) runner then exercise it: --node for one node, otherwise a full run.', (a) => a
269
286
  .option('file', { type: 'string', demandOption: true, describe: 'Path to a local *.workflow-v3.json template' })
@@ -288,6 +305,27 @@ function buildCli(rawArgs) {
288
305
  catch (err) {
289
306
  output.error(err.message, err.code || 'WORKFLOW_TEST_FAILED');
290
307
  }
308
+ })
309
+ .command('run <key>', 'Trigger an already-deployed workflow (no redeploy): --node for one node, otherwise a full run.', (a) => a
310
+ .positional('key', { type: 'string', demandOption: true, describe: 'Deployed workflow key (as shown by `workflow list`; the bare template key also works)' })
311
+ .option('runner', { type: 'string', demandOption: true, describe: 'Runner uid the workflow is deployed on' })
312
+ .option('body', { type: 'string', describe: 'Inline JSON: test-node inputData, or full-run request body (mutually exclusive with --input)' })
313
+ .option('input', { type: 'string', describe: 'Path to a JSON file: test-node inputData, or full-run request body' })
314
+ .option('node', { type: 'string', describe: 'Run a single node of the deployed workflow by id (uses test-node)' })
315
+ .option('trigger-key', { type: 'string', describe: 'api-key to pass to the runner if the trigger requires auth' }), async (argv) => {
316
+ const { runCommand } = await import('./functions/workflow/commands/run.js');
317
+ const { createApiClient: mkClient } = await import('./functions/helper/api-client.js');
318
+ const output = (0, output_1.createOutput)(!!argv.json);
319
+ try {
320
+ await runCommand(output, mkClient(), {
321
+ key: argv.key, runner: argv.runner,
322
+ body: argv.body, input: argv.input,
323
+ node: argv.node, triggerKey: argv['trigger-key'],
324
+ });
325
+ }
326
+ catch (err) {
327
+ output.error(err.message, err.code || 'WORKFLOW_RUN_FAILED');
328
+ }
291
329
  })
292
330
  .command('deploy', 'Validate (remote) then deploy a template to a runner. Confirms before going live.', (a) => a
293
331
  .option('file', { type: 'string', demandOption: true, describe: 'Path to a local *.workflow-v3.json template' })
@@ -406,6 +444,10 @@ function buildCli(rawArgs) {
406
444
  type: 'array',
407
445
  string: true,
408
446
  describe: 'Restrict the pull to one or more files / folders / globs (relative to baseFolder). Repeatable. With --strict, local deletion is also confined to the scope. Example: --path models/ --path data/products.csv',
447
+ })
448
+ .option('dest', {
449
+ type: 'string',
450
+ describe: 'Sandbox fetch: write the pulled files to this path instead of the workspace — no baseline/HEAD update, no conflict checks. An existing directory, a path ending in "/", or any multi-file match mirrors remote paths beneath it; with exactly one matching file, a plain file path is written as-is. Example: --path customers.csv --dest pulled/',
409
451
  }), async (argv) => {
410
452
  const { pullCommand } = await import('./functions/files/commands/pull.js');
411
453
  const { createApiClient } = await import('./functions/helper/api-client.js');
@@ -424,6 +466,7 @@ function buildCli(rawArgs) {
424
466
  yes: argv.yes,
425
467
  force: argv.force,
426
468
  paths: argv.path,
469
+ dest: argv.dest,
427
470
  });
428
471
  }
429
472
  catch (err) {
@@ -646,8 +689,7 @@ function buildCli(rawArgs) {
646
689
  });
647
690
  }
648
691
  catch (err) {
649
- console.error(err.message);
650
- process.exit(1);
692
+ (0, output_1.createOutput)(!!argv.json).error(err?.message || String(err), err?.code || 'CONFIG_SET_FAILED');
651
693
  }
652
694
  })
653
695
  .command('get', 'Print current projectId / apiKey / consoleApiUrl. apiKey redacted by default.', (a) => a
@@ -660,8 +702,7 @@ function buildCli(rawArgs) {
660
702
  });
661
703
  }
662
704
  catch (err) {
663
- console.error(err.message);
664
- process.exit(1);
705
+ (0, output_1.createOutput)(!!argv.json).error(err?.message || String(err), err?.code || 'CONFIG_GET_FAILED');
665
706
  }
666
707
  })
667
708
  .demandCommand(1);
@@ -977,6 +1018,7 @@ function buildCli(rawArgs) {
977
1018
  .option('attribute', { type: 'string', demandOption: true })
978
1019
  .option('exclude-zeros', { type: 'boolean' })
979
1020
  .option('exclude-undefineds', { type: 'boolean' })
1021
+ .option('exclude-unresolved', { type: 'boolean' })
980
1022
  .option('query', { type: 'string' })
981
1023
  .option('query-file', { type: 'string' })
982
1024
  .option('limit', { type: 'number', describe: 'Top-N facets (passed to SDK as count)' })
@@ -992,7 +1034,7 @@ function buildCli(rawArgs) {
992
1034
  try {
993
1035
  await facetsCommand(output, {
994
1036
  appId: argv.app, model: argv.model, attribute: argv.attribute,
995
- excludeZeros: argv.excludeZeros, excludeUndefineds: argv.excludeUndefineds, query: argv.query, queryFile: argv.queryFile,
1037
+ excludeZeros: argv.excludeZeros, excludeUndefineds: argv.excludeUndefineds, excludeUnresolved: argv.excludeUnresolved, query: argv.query, queryFile: argv.queryFile,
996
1038
  limit: argv.limit, sort: argv.sort, full: argv.full, includeResults: argv.includeResults,
997
1039
  });
998
1040
  }
@@ -1004,14 +1046,26 @@ function buildCli(rawArgs) {
1004
1046
  .option('app', { type: 'string' })
1005
1047
  .option('model', { type: 'string', demandOption: true })
1006
1048
  .option('attribute', { type: 'string', demandOption: true })
1007
- .option('types', { type: 'string', demandOption: true, describe: 'Comma-separated: distinct,count,sum,avg,min,max,group' })
1049
+ .option('types', { type: 'string', describe: 'Comma-separated: distinct,count,sum,avg,min,max,group. Optional when --bins/--group-options supply grouping.' })
1008
1050
  .option('query', { type: 'string' })
1009
1051
  .option('query-file', { type: 'string' })
1010
- .option('include-keys', { type: 'boolean', default: false, describe: 'Include row keys in distinct results' }), async (argv) => {
1052
+ .option('include-keys', { type: 'boolean', default: false, describe: 'Include row keys in distinct results' })
1053
+ .option('bins', { type: 'string', describe: 'Numeric ranges for grouping, e.g. 0-100,100-200,200-' })
1054
+ .option('group-options', { type: 'string', describe: 'Full groupOptions JSON' })
1055
+ .option('group-options-file', { type: 'string', describe: 'Path to groupOptions JSON' })
1056
+ .option('distinct-limit', { type: 'number', describe: 'Cap distinct values' })
1057
+ .option('exclude-zeros', { type: 'boolean' })
1058
+ .option('exclude-undefineds', { type: 'boolean' })
1059
+ .option('exclude-unresolved', { type: 'boolean' }), async (argv) => {
1011
1060
  const { aggregateCommand } = await import('./functions/app/commands/fn/aggregate.js');
1012
1061
  const output = (0, output_1.createOutput)(argv.json);
1013
1062
  try {
1014
- await aggregateCommand(output, { appId: argv.app, model: argv.model, attribute: argv.attribute, types: argv.types, query: argv.query, queryFile: argv.queryFile, includeKeys: argv.includeKeys });
1063
+ await aggregateCommand(output, {
1064
+ appId: argv.app, model: argv.model, attribute: argv.attribute, types: argv.types, query: argv.query, queryFile: argv.queryFile, includeKeys: argv.includeKeys,
1065
+ bins: argv.bins, groupOptions: argv.groupOptions, groupOptionsFile: argv.groupOptionsFile,
1066
+ distinctLimit: argv.distinctLimit, excludeZeros: argv.excludeZeros,
1067
+ excludeUndefineds: argv.excludeUndefineds, excludeUnresolved: argv.excludeUnresolved,
1068
+ });
1015
1069
  }
1016
1070
  catch (err) {
1017
1071
  output.error(err.message, err.code || 'FN_AGGREGATE_FAILED');
@@ -1023,11 +1077,21 @@ function buildCli(rawArgs) {
1023
1077
  .option('attribute', { type: 'string', demandOption: true })
1024
1078
  .option('query', { type: 'string' })
1025
1079
  .option('query-file', { type: 'string' })
1026
- .option('aggregate', { type: 'array', describe: 'Per-group aggregates, format <attribute>:<type[,type...]>. Repeat to combine.' }), async (argv) => {
1080
+ .option('aggregate', { type: 'array', describe: 'Per-group aggregates, format <attribute>:<type[,type...]>. Repeat to combine.' })
1081
+ .option('exclude-zeros', { type: 'boolean' })
1082
+ .option('exclude-undefineds', { type: 'boolean' })
1083
+ .option('exclude-unresolved', { type: 'boolean' })
1084
+ .option('sort', { type: 'string', describe: 'attr:DIR ordering, e.g. price:DESC' })
1085
+ .option('limit', { type: 'number' })
1086
+ .option('start', { type: 'number', describe: '0-based offset' }), async (argv) => {
1027
1087
  const { groupByCommand } = await import('./functions/app/commands/fn/group-by.js');
1028
1088
  const output = (0, output_1.createOutput)(argv.json);
1029
1089
  try {
1030
- await groupByCommand(output, { appId: argv.app, model: argv.model, attribute: argv.attribute, query: argv.query, queryFile: argv.queryFile, aggregate: argv.aggregate });
1090
+ await groupByCommand(output, {
1091
+ appId: argv.app, model: argv.model, attribute: argv.attribute, query: argv.query, queryFile: argv.queryFile, aggregate: argv.aggregate,
1092
+ excludeZeros: argv.excludeZeros, excludeUndefineds: argv.excludeUndefineds,
1093
+ excludeUnresolved: argv.excludeUnresolved, sort: argv.sort, limit: argv.limit, start: argv.start,
1094
+ });
1031
1095
  }
1032
1096
  catch (err) {
1033
1097
  output.error(err.message, err.code || 'FN_GROUPBY_FAILED');
@@ -1046,6 +1110,60 @@ function buildCli(rawArgs) {
1046
1110
  catch (err) {
1047
1111
  output.error(err.message, err.code || 'FN_METADATA_FAILED');
1048
1112
  }
1113
+ })
1114
+ .command('pivot', 'Multi-dimensional cross-tab (rows x columns x values)', (a) => a
1115
+ .option('app', { type: 'string' })
1116
+ .option('model', { type: 'string', demandOption: true })
1117
+ .option('rows', { type: 'array', describe: 'Row attribute(s); append :totals for row totals. Repeatable.' })
1118
+ .option('columns', { type: 'array', describe: 'Column attribute(s); append :totals. Repeatable.' })
1119
+ .option('values', { type: 'array', describe: 'Aggregations <attr>:<type[,type]>. Repeatable.' })
1120
+ .option('totals', { type: 'boolean', describe: 'Compute grand totals' })
1121
+ .option('spec', { type: 'string', describe: 'Full PivotOptions JSON (mutually exclusive with shorthand flags)' })
1122
+ .option('spec-file', { type: 'string', describe: 'Path to PivotOptions JSON' })
1123
+ .option('query', { type: 'string' })
1124
+ .option('query-file', { type: 'string' }), async (argv) => {
1125
+ const { pivotCommand } = await import('./functions/app/commands/fn/pivot.js');
1126
+ const output = (0, output_1.createOutput)(argv.json);
1127
+ try {
1128
+ await pivotCommand(output, {
1129
+ appId: argv.app, model: argv.model,
1130
+ rows: argv.rows, columns: argv.columns,
1131
+ values: argv.values, totals: argv.totals,
1132
+ spec: argv.spec, specFile: argv.specFile, query: argv.query, queryFile: argv.queryFile,
1133
+ });
1134
+ }
1135
+ catch (err) {
1136
+ output.error(err.message, err.code || 'FN_PIVOT_FAILED');
1137
+ }
1138
+ })
1139
+ .command('suggest', 'Typeahead suggestions for an attribute value', (a) => a
1140
+ .option('app', { type: 'string' })
1141
+ .option('model', { type: 'string', demandOption: true })
1142
+ .option('attribute', { type: 'string', demandOption: true })
1143
+ .option('value', { type: 'string', demandOption: true })
1144
+ .option('max', { type: 'number' })
1145
+ .option('relevant-data', { type: 'string', choices: ['filtered', 'all', 'excludeQuery'] })
1146
+ .option('calculate-result-keys', { type: 'boolean' })
1147
+ .option('exclude-undefineds', { type: 'boolean' })
1148
+ .option('exclude-nulls', { type: 'boolean' })
1149
+ .option('exclude-query', { type: 'string' })
1150
+ .option('exclude-query-file', { type: 'string' })
1151
+ .option('query', { type: 'string' })
1152
+ .option('query-file', { type: 'string' }), async (argv) => {
1153
+ const { suggestCommand } = await import('./functions/app/commands/fn/suggest.js');
1154
+ const output = (0, output_1.createOutput)(argv.json);
1155
+ try {
1156
+ await suggestCommand(output, {
1157
+ appId: argv.app, model: argv.model, attribute: argv.attribute, value: argv.value,
1158
+ max: argv.max, relevantData: argv.relevantData,
1159
+ calculateResultKeys: argv.calculateResultKeys, excludeUndefineds: argv.excludeUndefineds,
1160
+ excludeNulls: argv.excludeNulls, excludeQuery: argv.excludeQuery, excludeQueryFile: argv.excludeQueryFile,
1161
+ query: argv.query, queryFile: argv.queryFile,
1162
+ });
1163
+ }
1164
+ catch (err) {
1165
+ output.error(err.message, err.code || 'FN_SUGGEST_FAILED');
1166
+ }
1049
1167
  })
1050
1168
  .demandCommand(1))
1051
1169
  .command('loaders <subcommand>', 'Manage loaders on a daemon', (yyy) => yyy