priority-axi 0.0.0-stage → 0.2.0

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.
@@ -0,0 +1,388 @@
1
+ // Dispatch: home view with no command, help and version, then one command.
2
+ // Everything goes to stdout. Exit codes: 0 ok, 1 error, 2 usage.
3
+ import { encode } from '@toon-format/toon';
4
+ import { fields, screens } from '../commands/catalog.js';
5
+ import { create } from '../commands/create.js';
6
+ import { find as findRecords } from '../commands/find.js';
7
+ import { home } from '../commands/home.js';
8
+ import { changes, get, show } from '../commands/read.js';
9
+ import { refresh } from '../commands/refresh.js';
10
+ import { addLine, update, updateLine } from '../commands/update.js';
11
+ import { AxiError, usage } from '../errors.js';
12
+ import { errorText } from '../output/toon.js';
13
+ import { VERSION } from '../version.js';
14
+ import { parseCommand } from './parse.js';
15
+ import { BIN, CONNECTION_FLAGS, commandName, usageLine, } from './table.js';
16
+ export const DESCRIPTION = 'Read, create and update Priority ERP records over its REST API';
17
+ export const COMMANDS = [
18
+ {
19
+ name: '',
20
+ args: [],
21
+ flags: { ...CONNECTION_FLAGS },
22
+ summary: 'Home view: connection, Priority version, company, index and next steps',
23
+ run: home,
24
+ },
25
+ {
26
+ name: 'screens',
27
+ args: [{ name: '<text>', required: false }],
28
+ flags: {
29
+ limit: {
30
+ type: 'string',
31
+ value: '<n>',
32
+ summary: 'Rows to show, default 20, at most 2000',
33
+ },
34
+ full: { type: 'boolean', summary: 'Show every match' },
35
+ ...CONNECTION_FLAGS,
36
+ },
37
+ summary: 'Find screens by name, sub-screen title or field description',
38
+ run: screens,
39
+ },
40
+ {
41
+ name: 'fields',
42
+ args: [{ name: '<SCREEN>', required: true }],
43
+ flags: {
44
+ sub: {
45
+ type: 'string',
46
+ value: '<SUB>',
47
+ summary: 'Describe a sub-screen, such as ORDERITEMS',
48
+ },
49
+ all: { type: 'boolean', summary: 'Include internal IDs' },
50
+ full: {
51
+ type: 'boolean',
52
+ summary: 'Show every field without the size limit',
53
+ },
54
+ ...CONNECTION_FLAGS,
55
+ },
56
+ summary: "Describe a screen's fields, key and sub-screens",
57
+ run: fields,
58
+ },
59
+ {
60
+ name: 'get',
61
+ args: [{ name: '<SCREEN>', required: true }],
62
+ flags: {
63
+ where: {
64
+ type: 'string',
65
+ multiple: true,
66
+ value: '<F=V>',
67
+ summary: 'Filter: F=V, F!=V, F>V, F>=V, F<V or F<=V',
68
+ },
69
+ filter: {
70
+ type: 'string',
71
+ value: '<odata>',
72
+ summary: 'A raw OData $filter, combined with --where using and',
73
+ },
74
+ fields: { type: 'string', value: '<A,B>', summary: 'Columns to show' },
75
+ with: {
76
+ type: 'string',
77
+ multiple: true,
78
+ value: '<SUB>',
79
+ summary: 'Include sub-screen lines, such as ORDERITEMS',
80
+ },
81
+ sort: {
82
+ type: 'string',
83
+ value: '<F[:desc]>',
84
+ summary: 'Sort by a field; add :desc to reverse. Default: the key',
85
+ },
86
+ limit: {
87
+ type: 'string',
88
+ value: '<n>',
89
+ summary: 'Records per page, default 20, at most 500',
90
+ },
91
+ page: { type: 'string', value: '<n>', summary: 'Page number, default 1' },
92
+ full: {
93
+ type: 'boolean',
94
+ summary: 'Every non-empty field, no size limit',
95
+ },
96
+ ...CONNECTION_FLAGS,
97
+ },
98
+ summary: 'Read records from a screen',
99
+ run: get,
100
+ },
101
+ {
102
+ name: 'show',
103
+ args: [
104
+ { name: '<SCREEN>', required: true },
105
+ { name: '<key>', required: false },
106
+ ],
107
+ flags: {
108
+ key: {
109
+ type: 'string',
110
+ multiple: true,
111
+ value: '<F=V>',
112
+ summary: 'One part of a compound key',
113
+ },
114
+ with: {
115
+ type: 'string',
116
+ multiple: true,
117
+ value: '<SUB>',
118
+ summary: 'Include sub-screen lines',
119
+ },
120
+ all: { type: 'boolean', summary: 'Include internal IDs' },
121
+ full: { type: 'boolean', summary: 'Every field and line, no size limit' },
122
+ ...CONNECTION_FLAGS,
123
+ },
124
+ summary: 'Read one record by its key',
125
+ run: show,
126
+ },
127
+ {
128
+ name: 'changes',
129
+ args: [{ name: '<SCREEN>', required: true }],
130
+ flags: {
131
+ since: {
132
+ type: 'string',
133
+ required: true,
134
+ value: '<time>',
135
+ summary: 'From when: 7d, 24h, 2026-11-01 or a full UTC time',
136
+ },
137
+ where: {
138
+ type: 'string',
139
+ multiple: true,
140
+ value: '<F=V>',
141
+ summary: 'Filter, as for get',
142
+ },
143
+ fields: { type: 'string', value: '<A,B>', summary: 'Columns to show' },
144
+ limit: {
145
+ type: 'string',
146
+ value: '<n>',
147
+ summary: 'Records per page, default 20, at most 500',
148
+ },
149
+ page: { type: 'string', value: '<n>', summary: 'Page number, default 1' },
150
+ full: {
151
+ type: 'boolean',
152
+ summary: 'Every non-empty field, no size limit',
153
+ },
154
+ ...CONNECTION_FLAGS,
155
+ },
156
+ summary: 'Read records created or changed since a time (screens with a BPM status workflow)',
157
+ run: changes,
158
+ },
159
+ {
160
+ name: 'find',
161
+ args: [
162
+ { name: '<SCREEN>', required: true },
163
+ { name: '<words>', required: true, variadic: true },
164
+ ],
165
+ flags: {
166
+ sub: {
167
+ type: 'string',
168
+ value: '<SUB>',
169
+ summary: 'Search the lines of a sub-screen with their parent, such as CUSTOMERS --sub CUSTPROJECTS',
170
+ },
171
+ all: { type: 'boolean', summary: 'Include inactive records' },
172
+ limit: {
173
+ type: 'string',
174
+ value: '<n>',
175
+ summary: 'Matches per page, default 20, at most 200',
176
+ },
177
+ page: { type: 'string', value: '<n>', summary: 'Page number, default 1' },
178
+ refresh: {
179
+ type: 'boolean',
180
+ summary: 'Rebuild the local catalog now instead of after a day',
181
+ },
182
+ ...CONNECTION_FLAGS,
183
+ },
184
+ summary: 'Find records by words in their name or description, such as parts or customers',
185
+ run: findRecords,
186
+ },
187
+ {
188
+ name: 'create',
189
+ args: [
190
+ { name: '<SCREEN>', required: true },
191
+ // The F=V terms of a --line; its placeholder shows them.
192
+ { name: '<F=V>', required: false, variadic: true, hidden: true },
193
+ ],
194
+ flags: {
195
+ set: {
196
+ type: 'string',
197
+ multiple: true,
198
+ value: '<F=V>',
199
+ summary: 'A field of the new record',
200
+ },
201
+ line: {
202
+ type: 'string',
203
+ multiple: true,
204
+ value: '<SUB> <F=V>...',
205
+ summary: 'A sub-screen line: the sub-screen, then its fields',
206
+ },
207
+ 'json-file': {
208
+ type: 'string',
209
+ value: '<path>',
210
+ summary: 'The record as JSON instead of --set and --line',
211
+ },
212
+ 'dry-run': {
213
+ type: 'boolean',
214
+ summary: 'Check and show the request without sending it',
215
+ },
216
+ ...CONNECTION_FLAGS,
217
+ },
218
+ summary: 'Create a record; inside Comis the owner approves it first',
219
+ run: create,
220
+ },
221
+ {
222
+ name: 'update',
223
+ args: [
224
+ { name: '<SCREEN>', required: true },
225
+ { name: '<key>', required: true },
226
+ ],
227
+ flags: {
228
+ set: {
229
+ type: 'string',
230
+ multiple: true,
231
+ value: '<F=V>',
232
+ summary: 'A field to change',
233
+ },
234
+ 'dry-run': {
235
+ type: 'boolean',
236
+ summary: 'Check and show the request without sending it',
237
+ },
238
+ ...CONNECTION_FLAGS,
239
+ },
240
+ summary: 'Change fields of one record; inside Comis the owner approves it first',
241
+ run: update,
242
+ },
243
+ {
244
+ name: 'add-line',
245
+ args: [
246
+ { name: '<SCREEN>', required: true },
247
+ { name: '<key>', required: true },
248
+ { name: '<SUB>', required: true },
249
+ { name: '<F=V>', required: true, variadic: true },
250
+ ],
251
+ flags: {
252
+ 'dry-run': {
253
+ type: 'boolean',
254
+ summary: 'Check and show the request without sending it',
255
+ },
256
+ ...CONNECTION_FLAGS,
257
+ },
258
+ summary: "Add one line to a record's sub-screen; inside Comis the owner approves it first",
259
+ run: addLine,
260
+ },
261
+ {
262
+ name: 'update-line',
263
+ args: [
264
+ { name: '<SCREEN>', required: true },
265
+ { name: '<key>', required: true },
266
+ { name: '<SUB>', required: true },
267
+ { name: '<line-key>', required: true },
268
+ ],
269
+ flags: {
270
+ set: {
271
+ type: 'string',
272
+ multiple: true,
273
+ value: '<F=V>',
274
+ summary: 'A field of the line to change',
275
+ },
276
+ 'dry-run': {
277
+ type: 'boolean',
278
+ summary: 'Check and show the request without sending it',
279
+ },
280
+ ...CONNECTION_FLAGS,
281
+ },
282
+ summary: "Change one line of a record's sub-screen; inside Comis the owner approves it first",
283
+ run: updateLine,
284
+ },
285
+ {
286
+ name: 'refresh',
287
+ args: [],
288
+ flags: { ...CONNECTION_FLAGS },
289
+ summary: 'Rebuild the screen index from Priority now',
290
+ run: refresh,
291
+ },
292
+ {
293
+ name: 'help',
294
+ args: [{ name: '<command>', required: false }],
295
+ flags: {},
296
+ summary: 'List the commands, or show one command',
297
+ run: async () => '',
298
+ },
299
+ ];
300
+ const HOME = COMMANDS[0];
301
+ const HELP_FLAGS = new Set(['--help', '-h']);
302
+ const VERSION_FLAGS = new Set(['--version', '-v', '-V']);
303
+ export function topHelp() {
304
+ return `${encode({
305
+ description: DESCRIPTION,
306
+ usage: `${BIN} [command] [flags]`,
307
+ commands: COMMANDS.map((c) => ({
308
+ command: commandName(c),
309
+ summary: c.summary,
310
+ })),
311
+ settings: 'PRIORITY_URL and PRIORITY_PASSWORD; PRIORITY_USER, PRIORITY_COMPANY and PRIORITY_INI, or their flags',
312
+ })}\nhelp[1]:\n Run \`${BIN} help <command>\` for its flags\n`;
313
+ }
314
+ export function commandHelp(spec) {
315
+ const flags = Object.entries(spec.flags).map(([name, f]) => ({
316
+ flag: f.type === 'string' ? `--${name} ${f.value ?? '<value>'}` : `--${name}`,
317
+ summary: f.multiple ? `${f.summary} (repeatable)` : f.summary,
318
+ }));
319
+ return `${encode({
320
+ command: commandName(spec),
321
+ summary: spec.summary,
322
+ usage: usageLine(spec),
323
+ ...(flags.length ? { flags } : {}),
324
+ })}\n`;
325
+ }
326
+ function find(name) {
327
+ return COMMANDS.find((c) => c.name === name && c.name !== '');
328
+ }
329
+ function unknownCommand(name) {
330
+ const shown = /^[a-z][a-z-]{0,30}$/.test(name)
331
+ ? `\`${name}\``
332
+ : 'that command';
333
+ const list = COMMANDS.filter((c) => c.name).map((c) => c.name);
334
+ return usage(`Unknown command ${shown}. Commands: ${list.join(', ')}.`);
335
+ }
336
+ export async function main(argv, io) {
337
+ let spec = HOME;
338
+ let usageText = `${BIN} [command] [flags]`;
339
+ try {
340
+ const first = argv[0];
341
+ if (argv.length === 1 && first && VERSION_FLAGS.has(first)) {
342
+ io.stdout(`${VERSION}\n`);
343
+ return 0;
344
+ }
345
+ if (argv.length === 1 && first && HELP_FLAGS.has(first)) {
346
+ io.stdout(topHelp());
347
+ return 0;
348
+ }
349
+ let rest = argv;
350
+ if (first && !first.startsWith('-')) {
351
+ const found = find(first);
352
+ if (!found)
353
+ throw unknownCommand(first);
354
+ spec = found;
355
+ rest = argv.slice(1);
356
+ }
357
+ usageText = usageLine(spec);
358
+ const beforeTerminator = rest.includes('--')
359
+ ? rest.slice(0, rest.indexOf('--'))
360
+ : rest;
361
+ if (beforeTerminator.some((a) => HELP_FLAGS.has(a))) {
362
+ io.stdout(commandHelp(spec));
363
+ return 0;
364
+ }
365
+ const parsed = parseCommand(spec, rest);
366
+ if (spec.name === 'help') {
367
+ const target = parsed.positionals[0];
368
+ if (!target) {
369
+ io.stdout(topHelp());
370
+ return 0;
371
+ }
372
+ const found = find(target);
373
+ if (!found)
374
+ throw unknownCommand(target);
375
+ io.stdout(commandHelp(found));
376
+ return 0;
377
+ }
378
+ io.stdout(await spec.run({ ...parsed, io }));
379
+ return 0;
380
+ }
381
+ catch (error) {
382
+ const axi = error instanceof AxiError
383
+ ? error
384
+ : new AxiError('internal_error', 'priority-axi failed unexpectedly. Run the command once more; if it fails again, report it.');
385
+ io.stdout(errorText(axi, usageText));
386
+ return axi.exitCode;
387
+ }
388
+ }
@@ -0,0 +1,37 @@
1
+ // One command table drives parsing, --help and every usage line.
2
+ export const BIN = 'priority-axi';
3
+ /** Connection flags shared by every command that talks to Priority. */
4
+ export const CONNECTION_FLAGS = {
5
+ company: {
6
+ type: 'string',
7
+ value: '<code>',
8
+ summary: 'Priority company code (or PRIORITY_COMPANY)',
9
+ },
10
+ user: {
11
+ type: 'string',
12
+ value: '<name>',
13
+ summary: 'Priority API username (or PRIORITY_USER)',
14
+ },
15
+ ini: {
16
+ type: 'string',
17
+ value: '<file>',
18
+ summary: 'Priority ini segment, default tabula.ini (or PRIORITY_INI)',
19
+ },
20
+ };
21
+ export function commandName(spec) {
22
+ return spec.name ? `${BIN} ${spec.name}` : BIN;
23
+ }
24
+ export function usageLine(spec) {
25
+ const args = spec.args
26
+ .filter((a) => !a.hidden)
27
+ .map((a) => {
28
+ const name = a.variadic ? `${a.name}...` : a.name;
29
+ return a.required ? name : `[${name}]`;
30
+ });
31
+ const flags = Object.entries(spec.flags).map(([name, f]) => {
32
+ const text = f.type === 'string' ? `--${name} ${f.value ?? '<value>'}` : `--${name}`;
33
+ const shown = f.required ? text : `[${text}]`;
34
+ return f.multiple ? `${shown}...` : shown;
35
+ });
36
+ return [commandName(spec), ...args, ...flags].join(' ');
37
+ }
@@ -0,0 +1,180 @@
1
+ // screens and fields: offline over the screen index once it is built.
2
+ import { resolveScreen, resolveSub, } from '../index/build.js';
3
+ import { readReach } from '../index/cache.js';
4
+ import { bounded, cut, render } from '../output/toon.js';
5
+ import { builtNote, commandLine, intFlag, open, screenIndex, shellWord, str, } from './common.js';
6
+ function scoreScreen(name, type, q) {
7
+ const lower = name.toLowerCase();
8
+ if (lower === q)
9
+ return { name, score: 0, match: 'name' };
10
+ if (lower.startsWith(q))
11
+ return { name, score: 1, match: 'name' };
12
+ if (lower.includes(q))
13
+ return { name, score: 2, match: 'name' };
14
+ const sub = type.subs.find((s) => s.name.toLowerCase().includes(q) || s.title?.toLowerCase().includes(q));
15
+ if (sub) {
16
+ return {
17
+ name,
18
+ score: 3,
19
+ match: `sub ${sub.name}${sub.title ? ` (${sub.title})` : ''}`,
20
+ };
21
+ }
22
+ const field = type.fields.find((f) => f.name.toLowerCase() === q || f.description?.toLowerCase().includes(q));
23
+ if (field) {
24
+ return {
25
+ name,
26
+ score: 4,
27
+ match: `field ${field.name}${field.description ? ` (${field.description})` : ''}`,
28
+ };
29
+ }
30
+ return undefined;
31
+ }
32
+ export async function screens(input) {
33
+ const s = open(input);
34
+ const loaded = await screenIndex(s);
35
+ const { index } = loaded;
36
+ const text = input.positionals[0]?.trim();
37
+ const q = text?.toLowerCase();
38
+ const limit = intFlag(input.values.limit, 'limit', 20, 1, 2000);
39
+ const full = input.values.full === true;
40
+ const reach = readReach(s.dir);
41
+ const api = (name) => reach[name]?.api ?? 'unknown';
42
+ const rank = (name) => api(name) === 'yes' ? 0 : api(name) === 'unknown' ? 1 : 2;
43
+ const hits = [];
44
+ for (const [name, typeName] of Object.entries(index.sets)) {
45
+ const type = index.types[typeName];
46
+ if (!type)
47
+ continue;
48
+ const hit = q
49
+ ? scoreScreen(name, type, q)
50
+ : { name, score: 0, match: null };
51
+ if (hit)
52
+ hits.push(hit);
53
+ }
54
+ hits.sort((a, b) => a.score - b.score ||
55
+ rank(a.name) - rank(b.name) ||
56
+ a.name.localeCompare(b.name));
57
+ const rows = hits.map((h) => {
58
+ const type = index.types[index.sets[h.name] ?? ''];
59
+ return {
60
+ name: h.name,
61
+ key: type?.key.length ? type.key.join('+') : null,
62
+ api: api(h.name),
63
+ ...(q ? { match: h.match } : { fields: type?.fields.length ?? 0 }),
64
+ };
65
+ });
66
+ const noun = (n) => (n === 1 ? 'screen' : 'screens');
67
+ const total = rows.length;
68
+ const capped = full ? total : Math.min(limit, total);
69
+ const what = q
70
+ ? `${total} ${noun(total)} match ${text}`
71
+ : `${total} ${noun(total)}`;
72
+ if (!total) {
73
+ return render({ summary: what, ...builtNote(loaded) }, [
74
+ 'Run `priority-axi screens` to list every screen',
75
+ ]);
76
+ }
77
+ return bounded({
78
+ total: capped,
79
+ narrower: `priority-axi screens ${text ? `${shellWord(text)} ` : ''}--limit 20`,
80
+ build: (shown, fieldLimit) => {
81
+ const listed = rows
82
+ .slice(0, shown)
83
+ .map((r) => 'match' in r &&
84
+ typeof r.match === 'string' &&
85
+ Number.isFinite(fieldLimit)
86
+ ? { ...r, match: cut(r.match, Math.min(fieldLimit, 80)) }
87
+ : r);
88
+ const help = [];
89
+ if (shown < total) {
90
+ help.push(`Run \`${commandLine('screens', text ? [text] : [], input.values, { full: '', limit: null })}\` to list all ${total}`);
91
+ }
92
+ help.push("Run `priority-axi fields <SCREEN>` to see a screen's fields");
93
+ return render({
94
+ summary: shown < total ? `${what} (${shown} shown)` : what,
95
+ ...builtNote(loaded),
96
+ screens: listed,
97
+ }, help);
98
+ },
99
+ }, full);
100
+ }
101
+ export function shortType(f) {
102
+ switch (f.type) {
103
+ case 'String':
104
+ return f.max ? `text(${f.max})` : 'text';
105
+ case 'Int16':
106
+ case 'Int32':
107
+ case 'Int64':
108
+ return 'int';
109
+ case 'Decimal':
110
+ case 'Double':
111
+ case 'Single':
112
+ return 'decimal';
113
+ case 'DateTimeOffset':
114
+ return f.dateType === 'Date' ? 'date' : 'datetime';
115
+ case 'Boolean':
116
+ return 'bool';
117
+ default:
118
+ return f.type.toLowerCase();
119
+ }
120
+ }
121
+ export async function fields(input) {
122
+ const s = open(input);
123
+ const loaded = await screenIndex(s);
124
+ const { index } = loaded;
125
+ const screen = resolveScreen(index, input.positionals[0] ?? '');
126
+ const subName = str(input.values.sub);
127
+ const sub = subName ? resolveSub(index, screen, subName) : undefined;
128
+ const type = sub ? sub.def : screen.type;
129
+ const all = input.values.all === true;
130
+ const full = input.values.full === true;
131
+ const listed = type.fields.filter((f) => all || !f.internalId || type.key.includes(f.name));
132
+ const hidden = type.fields.length - listed.length;
133
+ const rows = listed.map((f) => {
134
+ const flags = [
135
+ type.key.includes(f.name) ? 'key' : '',
136
+ f.readOnly ? 'read-only' : '',
137
+ f.internalId ? 'id' : '',
138
+ ].filter(Boolean);
139
+ return {
140
+ name: f.name,
141
+ type: shortType(f),
142
+ flags: flags.length ? flags.join(' ') : null,
143
+ description: f.description ?? null,
144
+ };
145
+ });
146
+ const target = sub ? `${screen.name} > ${sub.name}` : screen.name;
147
+ const summary = `${type.fields.length} fields${hidden ? ` (${hidden} internal ID${hidden === 1 ? '' : 's'} hidden; --all shows them)` : ''}`;
148
+ const head = {
149
+ screen: target,
150
+ ...(sub?.title ? { title: sub.title } : {}),
151
+ ...(sub ? { holds: sub.many ? 'lines' : 'one record' } : {}),
152
+ key: type.key.length ? type.key.join(', ') : null,
153
+ summary,
154
+ ...builtNote(loaded),
155
+ };
156
+ const subs = sub ? [] : screen.type.subs.map((x) => x.name);
157
+ return bounded({
158
+ total: rows.length,
159
+ narrower: `priority-axi fields ${screen.name}`,
160
+ build: (shown) => {
161
+ const help = [
162
+ `Run \`priority-axi get ${screen.name} --limit 5\` to read records`,
163
+ ];
164
+ if (shown < rows.length) {
165
+ help.push(`Run \`${commandLine('fields', [screen.name], input.values, { full: '' })}\` to list all ${rows.length} fields without the size limit (${shown} shown)`);
166
+ }
167
+ else if (subs.length) {
168
+ help.push(`Run \`priority-axi fields ${screen.name} --sub <SUB>\` for a sub-screen`);
169
+ }
170
+ return render({
171
+ ...head,
172
+ fields: rows.slice(0, shown),
173
+ ...(shown < rows.length
174
+ ? { omitted: `${rows.length - shown} fields not shown` }
175
+ : {}),
176
+ ...(subs.length ? { subforms: subs } : {}),
177
+ }, help);
178
+ },
179
+ }, full);
180
+ }