priority-axi 0.0.0-stage → 0.1.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 priority-axi contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE ADDED
@@ -0,0 +1,13 @@
1
+ priority-axi
2
+ Copyright (c) 2026 priority-axi contributors
3
+ Licensed under the MIT License; see LICENSE.
4
+
5
+ This package depends on the following third-party software at run time.
6
+
7
+ @toon-format/toon 4.4.0
8
+ https://github.com/toon-format/toon
9
+ Copyright (c) 2025-PRESENT Johann Schopplich
10
+ MIT License
11
+
12
+ Priority is a trademark of Priority Software Ltd. priority-axi is not made,
13
+ endorsed or supported by Priority Software Ltd.
package/README.md CHANGED
@@ -1,3 +1,178 @@
1
- # Temporary Holding Version
1
+ # priority-axi
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/comisai/priority-axi/actions/workflows/ci.yml/badge.svg)](https://github.com/comisai/priority-axi/actions/workflows/ci.yml)
4
+ [![npm](https://img.shields.io/npm/v/priority-axi.svg)](https://www.npmjs.com/package/priority-axi)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+
7
+ A command-line tool that lets AI agents read and create records in Priority ERP through its REST API (OData).
8
+
9
+ priority-axi is an AXI, an agent experience interface. Every command:
10
+ - prints compact [TOON](https://github.com/toon-format/toon) text on stdout, bounded in size;
11
+ - checks its input against the server's own metadata, and says exactly what is wrong;
12
+ - ends with hints for the next command;
13
+ - sends a write once and never retries it.
14
+
15
+ It was built to run inside Comis, behind the Comis Gate, and it works just as well on its own.
16
+
17
+ > **Status:** early development (0.x). Reads and creates are tested end to end against Priority 23.1.
18
+
19
+ ## Requirements
20
+
21
+ - Node.js 22.18 or later.
22
+ - A Priority server with the REST API, an API user, and the screens you need opened to the API ([see below](#priority-administrator-setup)).
23
+
24
+ ## Install
25
+
26
+ ```sh
27
+ npm install -g priority-axi
28
+ ```
29
+
30
+ Each release is published from GitHub Actions with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), so you can check that it was built from this repository. To run from source instead, see [Development](#development).
31
+
32
+ ## Configure
33
+
34
+ | Variable | Flag | Meaning |
35
+ | --- | --- | --- |
36
+ | `PRIORITY_URL` | | `https://host`, or the full service root `https://host/odata/Priority/<ini>/<company>` |
37
+ | `PRIORITY_USER` | `--user` | The API username |
38
+ | `PRIORITY_PASSWORD` | | The password. Inside Comis it is a placeholder that the Gate replaces. |
39
+ | `PRIORITY_COMPANY` | `--company` | The company code |
40
+ | `PRIORITY_INI` | `--ini` | The ini file in the URL. The default is `tabula.ini`. |
41
+
42
+ A flag overrides its variable. Plain `http://` is accepted only for `localhost` and `127.0.0.1`.
43
+
44
+ ### Priority administrator setup
45
+
46
+ The REST API reads only the screens that the administrator has opened to it. Ask them to:
47
+ 1. Add the screens you need to **Limited Access / API Forms**, for example CUSTOMERS, LOGPART and ORDERS. Their sub-screens, such as ORDERITEMS, come with them.
48
+ 2. Give the API user an API license, and only the privileges it needs.
49
+
50
+ Until then, reads end with `code: screen_not_enabled`. The home view, `screens`, `fields` and `refresh` work without it.
51
+
52
+ ## Usage
53
+
54
+ ```text
55
+ priority-axi home view: connection, version, company, next steps
56
+ priority-axi screens [<text>] find screens by name or description
57
+ priority-axi fields <SCREEN> [--sub <SUB>] a screen's fields, key and sub-screens
58
+ priority-axi get <SCREEN> [--where F=V]... [--fields A,B] [--with <SUB>]... [--sort F[:desc]] [--limit N] [--page N]
59
+ priority-axi show <SCREEN> <key> [--with <SUB>]...
60
+ priority-axi changes <SCREEN> --since 7d recent changes, on screens with a BPM status workflow
61
+ priority-axi find <SCREEN> <words>... records by words in their name or description
62
+ priority-axi create <SCREEN> --set F=V... [--line <SUB> F=V...]... [--dry-run]
63
+ priority-axi refresh rebuild the screen index
64
+ priority-axi help [<command>] every flag of a command
65
+ ```
66
+
67
+ Every command that talks to Priority also takes `--company`, `--user` and `--ini`.
68
+
69
+ ```console
70
+ $ priority-axi get ORDERS --where CUSTNAME=C1002 --with ORDERITEMS --limit 2
71
+ summary: "2 records from ORDERS, more exist"
72
+ records[2]:
73
+ - ORDNAME: SO26000102
74
+ CUSTNAME: C1002
75
+ CDES: Example Customer 2 Ltd
76
+ CURDATE: 2026-10-04
77
+ ORDERITEMS[2]{KLINE,PARTNAME,PDES,TQUANT}:
78
+ 1,P-100,Part 100,1
79
+ 2,P-101,Part 101,2
80
+ - ORDNAME: SO26000105
81
+ ...
82
+ help[2]:
83
+ Run `priority-axi get ORDERS --where CUSTNAME=C1002 --with ORDERITEMS --limit 2 --page 2` for the next 2
84
+ Run `priority-axi show ORDERS <ORDNAME>` for one record
85
+
86
+ $ priority-axi get ORDERS --where NOSUCH=1
87
+ message: ORDERS has no field NOSUCH. Run `priority-axi fields ORDERS` to list them.
88
+ code: usage
89
+ usage: "priority-axi get <SCREEN> [--where <F=V>]... [--filter <odata>] [--fields <A,B>] ..."
90
+ ```
91
+
92
+ More examples:
93
+
94
+ ```sh
95
+ priority-axi screens customer
96
+ priority-axi fields CUSTOMERS
97
+ priority-axi show ORDERS SO26000102 --with ORDERITEMS --with ORDERSTEXT
98
+ priority-axi changes CUSTOMERS --since 7d
99
+ priority-axi find LOGPART צינור ביוב 110
100
+ priority-axi create ORDERS --set CUSTNAME=C1001 --line ORDERITEMS PARTNAME=P1 TQUANT=2 --dry-run
101
+ ```
102
+
103
+ ### Filters
104
+
105
+ `--where` takes `F=V`, `F!=V`, `F>V`, `F>=V`, `F<V` and `F<=V`. Values are typed from the screen's metadata, so you never write OData quotes. `--filter` passes raw OData for anything else the server supports.
106
+
107
+ Priority answers 501 to `contains` and `startswith`. For text that starts with `ABC`, use a range: `--where 'F>=ABC' --where 'F<ABD'`.
108
+
109
+ Always filter large document screens such as orders and invoices. Without a filter, Priority goes through every record before it answers, even when you ask for one.
110
+
111
+ ### Finding records by words
112
+
113
+ Priority cannot search inside text, so `find` keeps a local copy of a screen's catalog, refreshed daily: the key, description, unit, family and status. It matches as follows:
114
+ - **Every word must appear.** A word matches the start of a word, after Hebrew prefix letters, so `ביוב` finds `לביוב`.
115
+ - **Numbers match only as whole numbers.** `4` matches neither `4000` nor `SN4`.
116
+ - **Spelling variants are ignored:** Hebrew points, final letter forms, and `״`/`׳` against `"`/`'`.
117
+
118
+ Records that are not in use are left out unless you pass `--all`. When no record has every word, the closest ones are listed with the words they lack. `--sub` searches sub-screen lines together with their parent, for example `find CUSTOMERS --sub CUSTPROJECTS`.
119
+
120
+ ## Output and errors
121
+
122
+ - **Lists** say how many records they show and whether more exist. Priority reports no totals.
123
+ - **Size:** long values are cut at 500 characters, and the whole output at about 4,000. `--full` lifts both limits, up to 256 KB.
124
+ - **Text safety:** invisible and bidirectional control characters are shown as `\uXXXX`, and values that look like credentials are withheld. Remarks, which Priority stores as HTML, are shown as plain text.
125
+ - **Errors** print `message`, `code` and `usage` on stdout.
126
+ - **Exit codes:** 0 on success, 1 on an error, 2 on a usage error.
127
+
128
+ | Code | Meaning |
129
+ | --- | --- |
130
+ | `usage` | The command line is wrong; `usage` shows the right form |
131
+ | `not_connected`, `missing_setting` | A setting is missing |
132
+ | `auth_failed` | Priority refused the username or password |
133
+ | `company_not_found` | The API user cannot reach that company |
134
+ | `screen_not_enabled` | The screen is not in Limited Access / API Forms |
135
+ | `not_found` | No record has that key |
136
+ | `already_exists` | A create clashed with an existing key |
137
+ | `priority_rejected` | Priority refused the request; its own message is shown |
138
+ | `unsupported_query` | Priority cannot run that query |
139
+ | `rate_limited` | Too many requests; wait and try again |
140
+ | `held_for_approval`, `reconnect_needed`, `refused` | Inside Comis: the owner must approve, the owner must reconnect, or the Gate refused |
141
+ | `unreachable`, `priority_error` | The server could not be reached, or it failed |
142
+ | `output_too_large` | Even `--full` would exceed 256 KB; narrow the query |
143
+ | `internal_error` | A bug in priority-axi; please [report it](https://github.com/comisai/priority-axi/issues) |
144
+
145
+ ## Writes
146
+
147
+ `create` checks every field against the metadata before it sends anything: the field must exist and be writable, and its value must have the right type and length.
148
+ - **Dry run:** `--dry-run` shows the request and how many API transactions it will cost: one per record and one per line.
149
+ - **Sent once:** a create is never retried. Inside Comis, the Gate holds it until the owner approves it.
150
+ - **Fields the metadata does not mark:** Priority may require them, and then refuses with `priority_rejected` and its own message.
151
+
152
+ ## Comis
153
+
154
+ [`comis/`](comis/README.md) holds the Comis connector bundle:
155
+ - the catalog entry and the Gate template;
156
+ - the wrapper;
157
+ - the agent skills, including one that turns a plumber's Hebrew order message into a draft sales order.
158
+
159
+ ## Development
160
+
161
+ ```sh
162
+ npm ci
163
+ npm run check # type-check, lint, unit and contract tests against a fake Priority
164
+ npm run build # dist/bin/priority-axi.js
165
+ npm run test:dist # contract and AXI-principle tests against the built CLI
166
+ ```
167
+
168
+ The live tests against a real server are opt-in. Run `node test/live/priority-live.mjs --help` for how to use them. The design is in [`docs/priority-axi-design.md`](docs/priority-axi-design.md).
169
+
170
+ ## Contributing
171
+
172
+ Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first, and follow the [Code of Conduct](CODE_OF_CONDUCT.md). Report security issues privately, as described in [SECURITY.md](SECURITY.md).
173
+
174
+ ## License
175
+
176
+ MIT; see [LICENSE](LICENSE). Third-party notices are in [NOTICE](NOTICE).
177
+
178
+ Priority is a trademark of Priority Software Ltd. This project is not affiliated with or endorsed by Priority Software.
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../cli/run.js';
3
+ import { defaultDeps } from '../http.js';
4
+ // A reader that closes early, as in `priority-axi ... | head`, is a normal end.
5
+ process.stdout.on('error', (error) => {
6
+ if (error.code === 'EPIPE')
7
+ process.exit(0);
8
+ throw error;
9
+ });
10
+ process.exitCode = await main(process.argv.slice(2), {
11
+ stdout: (text) => {
12
+ process.stdout.write(text);
13
+ },
14
+ env: process.env,
15
+ now: () => new Date(),
16
+ http: defaultDeps,
17
+ });
@@ -0,0 +1,69 @@
1
+ // Strict parsing with node:util parseArgs, following the Comis AXI fixture:
2
+ // unknown flags, repeated single flags, extra arguments and values on boolean
3
+ // flags are refused. A refusal names the flag, never its value. "--" ends flags.
4
+ import { parseArgs } from 'node:util';
5
+ import { usage } from '../errors.js';
6
+ import { commandName, } from './table.js';
7
+ const shownFlag = (raw) => /^--?[A-Za-z0-9][A-Za-z0-9-]{0,40}$/.test(raw) ? raw : 'that flag';
8
+ export function parseCommand(spec, argv) {
9
+ const name = commandName(spec);
10
+ const options = {};
11
+ for (const [flag, f] of Object.entries(spec.flags)) {
12
+ options[flag] = f.multiple
13
+ ? { type: f.type, multiple: true }
14
+ : { type: f.type };
15
+ }
16
+ const valid = Object.keys(spec.flags).map((f) => `--${f}`);
17
+ let result;
18
+ try {
19
+ result = parseArgs({
20
+ args: argv,
21
+ options,
22
+ strict: false,
23
+ allowPositionals: true,
24
+ tokens: true,
25
+ });
26
+ }
27
+ catch {
28
+ throw usage(`Invalid arguments for \`${name}\`.`);
29
+ }
30
+ const seen = new Set();
31
+ for (const token of result.tokens) {
32
+ if (token.kind !== 'option')
33
+ continue;
34
+ const f = spec.flags[token.name];
35
+ if (!f) {
36
+ throw usage(`Unknown flag ${shownFlag(token.rawName)} for \`${name}\`. ${valid.length ? `Valid flags: ${valid.join(', ')}.` : 'It takes no flags.'}`);
37
+ }
38
+ if (f.type === 'boolean' && token.inlineValue)
39
+ throw usage(`--${token.name} takes no value.`);
40
+ if (f.type === 'string' &&
41
+ (token.value === undefined || token.value === '')) {
42
+ throw usage(`--${token.name} needs a value: --${token.name} ${f.value ?? '<value>'}.`);
43
+ }
44
+ if (!f.multiple && seen.has(token.name))
45
+ throw usage(`--${token.name} is given more than once.`);
46
+ seen.add(token.name);
47
+ }
48
+ const positionals = result.positionals;
49
+ const required = spec.args.filter((a) => a.required);
50
+ if (positionals.length < required.length) {
51
+ throw usage(`Missing ${required[positionals.length]?.name ?? 'argument'} for \`${name}\`.`);
52
+ }
53
+ const variadic = spec.args.at(-1)?.variadic === true;
54
+ if (!variadic && positionals.length > spec.args.length) {
55
+ throw usage(spec.args.length
56
+ ? `\`${name}\` takes ${spec.args.map((a) => a.name).join(' ')}; there is an extra argument.`
57
+ : `\`${name}\` takes no arguments.`);
58
+ }
59
+ const tokens = [];
60
+ for (const token of result.tokens) {
61
+ if (token.kind === 'option') {
62
+ tokens.push({ kind: 'option', name: token.name, value: token.value });
63
+ }
64
+ else if (token.kind === 'positional') {
65
+ tokens.push({ kind: 'positional', value: token.value });
66
+ }
67
+ }
68
+ return { values: result.values, positionals, tokens };
69
+ }
@@ -0,0 +1,323 @@
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 { AxiError, usage } from '../errors.js';
11
+ import { errorText } from '../output/toon.js';
12
+ import { VERSION } from '../version.js';
13
+ import { parseCommand } from './parse.js';
14
+ import { BIN, CONNECTION_FLAGS, commandName, usageLine, } from './table.js';
15
+ export const DESCRIPTION = 'Read and create Priority ERP records over its REST API';
16
+ export const COMMANDS = [
17
+ {
18
+ name: '',
19
+ args: [],
20
+ flags: { ...CONNECTION_FLAGS },
21
+ summary: 'Home view: connection, Priority version, company, index and next steps',
22
+ run: home,
23
+ },
24
+ {
25
+ name: 'screens',
26
+ args: [{ name: '<text>', required: false }],
27
+ flags: {
28
+ limit: {
29
+ type: 'string',
30
+ value: '<n>',
31
+ summary: 'Rows to show, default 20, at most 2000',
32
+ },
33
+ full: { type: 'boolean', summary: 'Show every match' },
34
+ ...CONNECTION_FLAGS,
35
+ },
36
+ summary: 'Find screens by name, sub-screen title or field description',
37
+ run: screens,
38
+ },
39
+ {
40
+ name: 'fields',
41
+ args: [{ name: '<SCREEN>', required: true }],
42
+ flags: {
43
+ sub: {
44
+ type: 'string',
45
+ value: '<SUB>',
46
+ summary: 'Describe a sub-screen, such as ORDERITEMS',
47
+ },
48
+ all: { type: 'boolean', summary: 'Include internal IDs' },
49
+ full: {
50
+ type: 'boolean',
51
+ summary: 'Show every field without the size limit',
52
+ },
53
+ ...CONNECTION_FLAGS,
54
+ },
55
+ summary: "Describe a screen's fields, key and sub-screens",
56
+ run: fields,
57
+ },
58
+ {
59
+ name: 'get',
60
+ args: [{ name: '<SCREEN>', required: true }],
61
+ flags: {
62
+ where: {
63
+ type: 'string',
64
+ multiple: true,
65
+ value: '<F=V>',
66
+ summary: 'Filter: F=V, F!=V, F>V, F>=V, F<V or F<=V',
67
+ },
68
+ filter: {
69
+ type: 'string',
70
+ value: '<odata>',
71
+ summary: 'A raw OData $filter, combined with --where using and',
72
+ },
73
+ fields: { type: 'string', value: '<A,B>', summary: 'Columns to show' },
74
+ with: {
75
+ type: 'string',
76
+ multiple: true,
77
+ value: '<SUB>',
78
+ summary: 'Include sub-screen lines, such as ORDERITEMS',
79
+ },
80
+ sort: {
81
+ type: 'string',
82
+ value: '<F[:desc]>',
83
+ summary: 'Sort by a field; add :desc to reverse. Default: the key',
84
+ },
85
+ limit: {
86
+ type: 'string',
87
+ value: '<n>',
88
+ summary: 'Records per page, default 20, at most 500',
89
+ },
90
+ page: { type: 'string', value: '<n>', summary: 'Page number, default 1' },
91
+ full: {
92
+ type: 'boolean',
93
+ summary: 'Every non-empty field, no size limit',
94
+ },
95
+ ...CONNECTION_FLAGS,
96
+ },
97
+ summary: 'Read records from a screen',
98
+ run: get,
99
+ },
100
+ {
101
+ name: 'show',
102
+ args: [
103
+ { name: '<SCREEN>', required: true },
104
+ { name: '<key>', required: false },
105
+ ],
106
+ flags: {
107
+ key: {
108
+ type: 'string',
109
+ multiple: true,
110
+ value: '<F=V>',
111
+ summary: 'One part of a compound key',
112
+ },
113
+ with: {
114
+ type: 'string',
115
+ multiple: true,
116
+ value: '<SUB>',
117
+ summary: 'Include sub-screen lines',
118
+ },
119
+ all: { type: 'boolean', summary: 'Include internal IDs' },
120
+ full: { type: 'boolean', summary: 'Every field and line, no size limit' },
121
+ ...CONNECTION_FLAGS,
122
+ },
123
+ summary: 'Read one record by its key',
124
+ run: show,
125
+ },
126
+ {
127
+ name: 'changes',
128
+ args: [{ name: '<SCREEN>', required: true }],
129
+ flags: {
130
+ since: {
131
+ type: 'string',
132
+ required: true,
133
+ value: '<time>',
134
+ summary: 'From when: 7d, 24h, 2026-11-01 or a full UTC time',
135
+ },
136
+ where: {
137
+ type: 'string',
138
+ multiple: true,
139
+ value: '<F=V>',
140
+ summary: 'Filter, as for get',
141
+ },
142
+ fields: { type: 'string', value: '<A,B>', summary: 'Columns to show' },
143
+ limit: {
144
+ type: 'string',
145
+ value: '<n>',
146
+ summary: 'Records per page, default 20, at most 500',
147
+ },
148
+ page: { type: 'string', value: '<n>', summary: 'Page number, default 1' },
149
+ full: {
150
+ type: 'boolean',
151
+ summary: 'Every non-empty field, no size limit',
152
+ },
153
+ ...CONNECTION_FLAGS,
154
+ },
155
+ summary: 'Read records created or changed since a time (screens with a BPM status workflow)',
156
+ run: changes,
157
+ },
158
+ {
159
+ name: 'find',
160
+ args: [
161
+ { name: '<SCREEN>', required: true },
162
+ { name: '<words>', required: true, variadic: true },
163
+ ],
164
+ flags: {
165
+ sub: {
166
+ type: 'string',
167
+ value: '<SUB>',
168
+ summary: 'Search the lines of a sub-screen with their parent, such as CUSTOMERS --sub CUSTPROJECTS',
169
+ },
170
+ all: { type: 'boolean', summary: 'Include inactive records' },
171
+ limit: {
172
+ type: 'string',
173
+ value: '<n>',
174
+ summary: 'Matches per page, default 20, at most 200',
175
+ },
176
+ page: { type: 'string', value: '<n>', summary: 'Page number, default 1' },
177
+ refresh: {
178
+ type: 'boolean',
179
+ summary: 'Rebuild the local catalog now instead of after a day',
180
+ },
181
+ ...CONNECTION_FLAGS,
182
+ },
183
+ summary: 'Find records by words in their name or description, such as parts or customers',
184
+ run: findRecords,
185
+ },
186
+ {
187
+ name: 'create',
188
+ args: [
189
+ { name: '<SCREEN>', required: true },
190
+ // The F=V terms of a --line; its placeholder shows them.
191
+ { name: '<F=V>', required: false, variadic: true, hidden: true },
192
+ ],
193
+ flags: {
194
+ set: {
195
+ type: 'string',
196
+ multiple: true,
197
+ value: '<F=V>',
198
+ summary: 'A field of the new record',
199
+ },
200
+ line: {
201
+ type: 'string',
202
+ multiple: true,
203
+ value: '<SUB> <F=V>...',
204
+ summary: 'A sub-screen line: the sub-screen, then its fields',
205
+ },
206
+ 'json-file': {
207
+ type: 'string',
208
+ value: '<path>',
209
+ summary: 'The record as JSON instead of --set and --line',
210
+ },
211
+ 'dry-run': {
212
+ type: 'boolean',
213
+ summary: 'Check and show the request without sending it',
214
+ },
215
+ ...CONNECTION_FLAGS,
216
+ },
217
+ summary: 'Create a record; inside Comis the owner approves it first',
218
+ run: create,
219
+ },
220
+ {
221
+ name: 'refresh',
222
+ args: [],
223
+ flags: { ...CONNECTION_FLAGS },
224
+ summary: 'Rebuild the screen index from Priority now',
225
+ run: refresh,
226
+ },
227
+ {
228
+ name: 'help',
229
+ args: [{ name: '<command>', required: false }],
230
+ flags: {},
231
+ summary: 'List the commands, or show one command',
232
+ run: async () => '',
233
+ },
234
+ ];
235
+ const HOME = COMMANDS[0];
236
+ const HELP_FLAGS = new Set(['--help', '-h']);
237
+ const VERSION_FLAGS = new Set(['--version', '-v', '-V']);
238
+ export function topHelp() {
239
+ return `${encode({
240
+ description: DESCRIPTION,
241
+ usage: `${BIN} [command] [flags]`,
242
+ commands: COMMANDS.map((c) => ({
243
+ command: commandName(c),
244
+ summary: c.summary,
245
+ })),
246
+ settings: 'PRIORITY_URL and PRIORITY_PASSWORD; PRIORITY_USER, PRIORITY_COMPANY and PRIORITY_INI, or their flags',
247
+ })}\nhelp[1]:\n Run \`${BIN} help <command>\` for its flags\n`;
248
+ }
249
+ export function commandHelp(spec) {
250
+ const flags = Object.entries(spec.flags).map(([name, f]) => ({
251
+ flag: f.type === 'string' ? `--${name} ${f.value ?? '<value>'}` : `--${name}`,
252
+ summary: f.multiple ? `${f.summary} (repeatable)` : f.summary,
253
+ }));
254
+ return `${encode({
255
+ command: commandName(spec),
256
+ summary: spec.summary,
257
+ usage: usageLine(spec),
258
+ ...(flags.length ? { flags } : {}),
259
+ })}\n`;
260
+ }
261
+ function find(name) {
262
+ return COMMANDS.find((c) => c.name === name && c.name !== '');
263
+ }
264
+ function unknownCommand(name) {
265
+ const shown = /^[a-z][a-z-]{0,30}$/.test(name)
266
+ ? `\`${name}\``
267
+ : 'that command';
268
+ const list = COMMANDS.filter((c) => c.name).map((c) => c.name);
269
+ return usage(`Unknown command ${shown}. Commands: ${list.join(', ')}.`);
270
+ }
271
+ export async function main(argv, io) {
272
+ let spec = HOME;
273
+ let usageText = `${BIN} [command] [flags]`;
274
+ try {
275
+ const first = argv[0];
276
+ if (argv.length === 1 && first && VERSION_FLAGS.has(first)) {
277
+ io.stdout(`${VERSION}\n`);
278
+ return 0;
279
+ }
280
+ if (argv.length === 1 && first && HELP_FLAGS.has(first)) {
281
+ io.stdout(topHelp());
282
+ return 0;
283
+ }
284
+ let rest = argv;
285
+ if (first && !first.startsWith('-')) {
286
+ const found = find(first);
287
+ if (!found)
288
+ throw unknownCommand(first);
289
+ spec = found;
290
+ rest = argv.slice(1);
291
+ }
292
+ usageText = usageLine(spec);
293
+ const beforeTerminator = rest.includes('--')
294
+ ? rest.slice(0, rest.indexOf('--'))
295
+ : rest;
296
+ if (beforeTerminator.some((a) => HELP_FLAGS.has(a))) {
297
+ io.stdout(commandHelp(spec));
298
+ return 0;
299
+ }
300
+ const parsed = parseCommand(spec, rest);
301
+ if (spec.name === 'help') {
302
+ const target = parsed.positionals[0];
303
+ if (!target) {
304
+ io.stdout(topHelp());
305
+ return 0;
306
+ }
307
+ const found = find(target);
308
+ if (!found)
309
+ throw unknownCommand(target);
310
+ io.stdout(commandHelp(found));
311
+ return 0;
312
+ }
313
+ io.stdout(await spec.run({ ...parsed, io }));
314
+ return 0;
315
+ }
316
+ catch (error) {
317
+ const axi = error instanceof AxiError
318
+ ? error
319
+ : new AxiError('internal_error', 'priority-axi failed unexpectedly. Run the command once more; if it fails again, report it.');
320
+ io.stdout(errorText(axi, usageText));
321
+ return axi.exitCode;
322
+ }
323
+ }
@@ -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
+ }