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 +21 -0
- package/NOTICE +13 -0
- package/README.md +189 -2
- package/dist/bin/priority-axi.js +17 -0
- package/dist/cli/parse.js +69 -0
- package/dist/cli/run.js +388 -0
- package/dist/cli/table.js +37 -0
- package/dist/commands/catalog.js +180 -0
- package/dist/commands/common.js +173 -0
- package/dist/commands/create.js +207 -0
- package/dist/commands/find.js +153 -0
- package/dist/commands/home.js +56 -0
- package/dist/commands/read.js +264 -0
- package/dist/commands/refresh.js +26 -0
- package/dist/commands/update.js +124 -0
- package/dist/config.js +76 -0
- package/dist/errors.js +149 -0
- package/dist/http.js +120 -0
- package/dist/index/build.js +169 -0
- package/dist/index/cache.js +129 -0
- package/dist/index/catalog.js +216 -0
- package/dist/odata.js +152 -0
- package/dist/output/html.js +58 -0
- package/dist/output/shape.js +57 -0
- package/dist/output/text.js +48 -0
- package/dist/output/toon.js +78 -0
- package/dist/search.js +118 -0
- package/dist/version.js +2 -0
- package/package.json +55 -4
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
|
-
#
|
|
1
|
+
# priority-axi
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/comisai/priority-axi/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/priority-axi)
|
|
5
|
+
[](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
|
+
}
|