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.
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,190 @@
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, create and update records in Priority ERP through its REST API (OData).
8
+
9
+ priority-axi is an AXI, an agent experience interface. Every command:
10
+
11
+ - prints compact [TOON](https://github.com/toon-format/toon) text on stdout, bounded in size;
12
+ - checks its input against the server's own metadata, and says exactly what is wrong;
13
+ - ends with hints for the next command;
14
+ - sends a write once and never retries it.
15
+
16
+ It was built to run inside Comis, behind the Comis Gate, and it works just as well on its own.
17
+
18
+ > **Status:** early development (0.x). Reads and creates are tested end to end against Priority 23.1.
19
+
20
+ ## Requirements
21
+
22
+ - Node.js 22.18 or later.
23
+ - A Priority server with the REST API, an API user, and the screens you need opened to the API ([see below](#priority-administrator-setup)).
24
+
25
+ ## Install
26
+
27
+ ```sh
28
+ npm install -g priority-axi
29
+ ```
30
+
31
+ 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).
32
+
33
+ ## Configure
34
+
35
+ | Variable | Flag | Meaning |
36
+ | ------------------- | ----------- | -------------------------------------------------------------------------------------- |
37
+ | `PRIORITY_URL` | | `https://host`, or the full service root `https://host/odata/Priority/<ini>/<company>` |
38
+ | `PRIORITY_USER` | `--user` | The API username |
39
+ | `PRIORITY_PASSWORD` | | The password. Inside Comis it is a placeholder that the Gate replaces. |
40
+ | `PRIORITY_COMPANY` | `--company` | The company code |
41
+ | `PRIORITY_INI` | `--ini` | The ini file in the URL. The default is `tabula.ini`. |
42
+
43
+ A flag overrides its variable. Plain `http://` is accepted only for `localhost` and `127.0.0.1`.
44
+
45
+ ### Priority administrator setup
46
+
47
+ The REST API reads only the screens that the administrator has opened to it. Ask them to:
48
+
49
+ 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.
50
+ 2. Give the API user an API license, and only the privileges it needs.
51
+
52
+ Until then, reads end with `code: screen_not_enabled`. The home view, `screens`, `fields` and `refresh` work without it.
53
+
54
+ ## Usage
55
+
56
+ ```text
57
+ priority-axi home view: connection, version, company, next steps
58
+ priority-axi screens [<text>] find screens by name or description
59
+ priority-axi fields <SCREEN> [--sub <SUB>] a screen's fields, key and sub-screens
60
+ priority-axi get <SCREEN> [--where F=V]... [--fields A,B] [--with <SUB>]... [--sort F[:desc]] [--limit N] [--page N]
61
+ priority-axi show <SCREEN> <key> [--with <SUB>]...
62
+ priority-axi changes <SCREEN> --since 7d recent changes, on screens with a BPM status workflow
63
+ priority-axi find <SCREEN> <words>... records by words in their name or description
64
+ priority-axi create <SCREEN> --set F=V... [--line <SUB> F=V...]... [--dry-run]
65
+ priority-axi update <SCREEN> <key> --set F=V... [--dry-run] change a record
66
+ priority-axi add-line <SCREEN> <key> <SUB> F=V... [--dry-run] add a line to it
67
+ priority-axi update-line <SCREEN> <key> <SUB> <line-key> --set F=V... [--dry-run]
68
+ priority-axi refresh rebuild the screen index
69
+ priority-axi help [<command>] every flag of a command
70
+ ```
71
+
72
+ Every command that talks to Priority also takes `--company`, `--user` and `--ini`.
73
+
74
+ ```console
75
+ $ priority-axi get ORDERS --where CUSTNAME=C1002 --with ORDERITEMS --limit 2
76
+ summary: "2 records from ORDERS, more exist"
77
+ records[2]:
78
+ - ORDNAME: SO26000102
79
+ CUSTNAME: C1002
80
+ CDES: Example Customer 2 Ltd
81
+ CURDATE: 2026-10-04
82
+ ORDERITEMS[2]{KLINE,PARTNAME,PDES,TQUANT}:
83
+ 1,P-100,Part 100,1
84
+ 2,P-101,Part 101,2
85
+ - ORDNAME: SO26000105
86
+ ...
87
+ help[2]:
88
+ Run `priority-axi get ORDERS --where CUSTNAME=C1002 --with ORDERITEMS --limit 2 --page 2` for the next 2
89
+ Run `priority-axi show ORDERS <ORDNAME>` for one record
90
+
91
+ $ priority-axi get ORDERS --where NOSUCH=1
92
+ message: ORDERS has no field NOSUCH. Run `priority-axi fields ORDERS` to list them.
93
+ code: usage
94
+ usage: "priority-axi get <SCREEN> [--where <F=V>]... [--filter <odata>] [--fields <A,B>] ..."
95
+ ```
96
+
97
+ More examples:
98
+
99
+ ```sh
100
+ priority-axi screens customer
101
+ priority-axi fields CUSTOMERS
102
+ priority-axi show ORDERS SO26000102 --with ORDERITEMS --with ORDERSTEXT
103
+ priority-axi changes CUSTOMERS --since 7d
104
+ priority-axi find LOGPART צינור ביוב 110
105
+ priority-axi create ORDERS --set CUSTNAME=C1001 --line ORDERITEMS PARTNAME=P1 TQUANT=2 --dry-run
106
+ priority-axi add-line ORDERS SO26000102 ORDERITEMS PARTNAME=P1 TQUANT=2 --dry-run
107
+ priority-axi update-line ORDERS SO26000102 ORDERITEMS KLINE=1 --set TQUANT=3 --dry-run
108
+ ```
109
+
110
+ ### Filters
111
+
112
+ `--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.
113
+
114
+ Priority answers 501 to `contains` and `startswith`. For text that starts with `ABC`, use a range: `--where 'F>=ABC' --where 'F<ABD'`.
115
+
116
+ 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.
117
+
118
+ ### Finding records by words
119
+
120
+ 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:
121
+
122
+ - **Every word must appear.** A word matches the start of a word, after Hebrew prefix letters, so `ביוב` finds `לביוב`.
123
+ - **Numbers match only as whole numbers.** `4` matches neither `4000` nor `SN4`.
124
+ - **Spelling variants are ignored:** Hebrew points, final letter forms, and `״`/`׳` against `"`/`'`.
125
+
126
+ 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`.
127
+
128
+ ## Output and errors
129
+
130
+ - **Lists** say how many records they show and whether more exist. Priority reports no totals.
131
+ - **Size:** long values are cut at 500 characters, and the whole output at about 4,000. `--full` lifts both limits, up to 256 KB.
132
+ - **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.
133
+ - **Errors** print `message`, `code` and `usage` on stdout.
134
+ - **Exit codes:** 0 on success, 1 on an error, 2 on a usage error.
135
+
136
+ | Code | Meaning |
137
+ | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
138
+ | `usage` | The command line is wrong; `usage` shows the right form |
139
+ | `not_connected`, `missing_setting` | A setting is missing |
140
+ | `auth_failed` | Priority refused the username or password |
141
+ | `company_not_found` | The API user cannot reach that company |
142
+ | `screen_not_enabled` | The screen is not in Limited Access / API Forms |
143
+ | `not_found` | No record has that key |
144
+ | `already_exists` | A create clashed with an existing key |
145
+ | `priority_rejected` | Priority refused the request; its own message is shown |
146
+ | `unsupported_query` | Priority cannot run that query |
147
+ | `rate_limited` | Too many requests; wait and try again |
148
+ | `held_for_approval`, `reconnect_needed`, `refused` | Inside Comis: the owner must approve, the owner must reconnect, or the Gate refused |
149
+ | `unreachable`, `priority_error` | The server could not be reached, or it failed |
150
+ | `output_too_large` | Even `--full` would exceed 256 KB; narrow the query |
151
+ | `internal_error` | A bug in priority-axi; please [report it](https://github.com/comisai/priority-axi/issues) |
152
+
153
+ ## Writes
154
+
155
+ `create`, `update`, `add-line` and `update-line` check every field against the metadata before they send anything: the field must exist and be writable, and its value must have the right type and length.
156
+
157
+ - **Dry run:** `--dry-run` shows the request and how many API transactions it will cost: one per record and one per line.
158
+ - **Sent once:** a write is never retried. Inside Comis, the Gate holds it until the owner approves it.
159
+ - **Updates name the record in the path:** `PATCH ORDERS('SO26000102')`, `POST ORDERS('SO26000102')/ORDERITEMS_SUBFORM` and `PATCH ORDERS('SO26000102')/ORDERITEMS_SUBFORM(KLINE=1)`. A key value is a typed literal; it may not hold a slash, a percent sign, a backslash, a control character or two dots in a row, and the record's key fields cannot be changed. Deleting is not supported.
160
+ - **Fields the metadata does not mark:** Priority may require them, and then refuses with `priority_rejected` and its own message.
161
+
162
+ ## Comis
163
+
164
+ Comis ships priority-axi in its optional apps pack:
165
+
166
+ - a read skill, and a write skill that turns a plumber's Hebrew order message into a draft sales order for the owner's approval;
167
+ - a Gate catalog entry that injects the password only on the routes priority-axi uses, with a template for a server on a public host.
168
+
169
+ That integration lives in the Comis repository.
170
+
171
+ ## Development
172
+
173
+ ```sh
174
+ npm ci
175
+ npm run check # type-check, lint, unit and contract tests against a fake Priority
176
+ npm run build # dist/bin/priority-axi.js
177
+ npm run test:dist # contract and AXI-principle tests against the built CLI
178
+ ```
179
+
180
+ 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).
181
+
182
+ ## Contributing
183
+
184
+ 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).
185
+
186
+ ## License
187
+
188
+ MIT; see [LICENSE](LICENSE). Third-party notices are in [NOTICE](NOTICE).
189
+
190
+ 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
+ }