@indra.ai/deva 1.64.25 → 1.64.26

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/README.md CHANGED
@@ -21,11 +21,12 @@ Deva is a Vedic-inspired, event-based, context-aware Feature, Zone, Action and S
21
21
  9. [The workflow: features, zones, actions, states, intents, beliefs, contexts](#the-workflow)
22
22
  10. [Events](#events)
23
23
  11. [Error handling](#error-handling)
24
- 12. [Configuration files](#configuration-files)
25
- 13. [Testing](#testing)
26
- 14. [Method reference](#method-reference)
27
- 15. [License](#license)
28
- 16. [Links and author](#links-and-author)
24
+ 12. [Help](#help)
25
+ 13. [Configuration files](#configuration-files)
26
+ 14. [Testing](#testing)
27
+ 15. [Method reference](#method-reference)
28
+ 16. [License](#license)
29
+ 17. [Links and author](#links-and-author)
29
30
 
30
31
  ## Requirements
31
32
 
@@ -248,6 +249,46 @@ All core events are listed in `_data/events.json` (25). The ones you'll usually
248
249
 
249
250
  A method that rejects or throws ends up here. Most calls made while the Deva is inactive return or resolve `⭕️ OFFLINE` instead of throwing.
250
251
 
252
+ ## Help
253
+
254
+ Every Deva can carry its own help, written in **feecting**, the language Devas use to talk to each other. The name stands for Functional Expressive Emergent Cognitive Technical Intelligent Neural Generator a Key Value Pair Line Label Function Method Event Listener Zone Feature Action State Procedural Asynchronous Vector Programming Language. A Deva's help system starts small and grows as the Deva grows.
255
+
256
+ `help(msg, help_dir)` looks in the Deva's own folder and returns one section of a help file:
257
+
258
+ - `help_dir` is the Deva's base directory, usually `__dirname` of the Deva's file. Help files live in `<help_dir>/help/`.
259
+ - The first word of `msg` picks the file and the section, as `file:part`. The file defaults to `main`, and the part defaults to `MAIN` and is always matched in upper case.
260
+ - A section is the text between `::BEGIN:<PART>` and `::END:<PART>` (the `container` markers in `_data/index.js`).
261
+
262
+ ```text
263
+ my-deva/
264
+ index.js
265
+ help/
266
+ main.feecting
267
+ ask.feecting
268
+ ```
269
+
270
+ ```text
271
+ ::BEGIN:MAIN
272
+ # My Deva
273
+ p: What this Deva does and how to talk to it.
274
+ ::END:MAIN
275
+
276
+ ::BEGIN:ASK
277
+ ## Ask
278
+ p: Use #key method text to ask another Deva.
279
+ ::END:ASK
280
+ ```
281
+
282
+ | Call | Returns |
283
+ |---|---|
284
+ | `help('', __dirname)` or `help('main', __dirname)` | the `MAIN` section of `help/main.feecting` |
285
+ | `help('main:ask', __dirname)` | the `ASK` section of `help/main.feecting` |
286
+ | `help('ask', __dirname)` | the `MAIN` section of `help/ask.feecting` |
287
+ | a file or section that doesn't exist | `⛔️ HELP NOT FOUND` (`_messages.help_not_found`) |
288
+ | any call while the Deva is inactive | `⭕️ OFFLINE` |
289
+
290
+ The section comes back as raw feecting text, with the surrounding newlines kept, so the Deva can pass it on to be parsed or shown. A found section sets the `valid` state and `good` intent. A missing file sets `invalid` and `bad` tagged `help:not:exists`, and a missing section sets them tagged `help:not:found`. Neither one raises an error. If `help_dir` isn't passed, the promise rejects with a `TypeError` from `path.join`.
291
+
251
292
  ## Configuration files
252
293
 
253
294
  | File | Contents |
@@ -266,7 +307,22 @@ Each JSON file has `id`, `title`, `copyright`, `VLA` and `DATA`, and the values
266
307
  npm test
267
308
  ```
268
309
 
269
- This runs `node tests` (`tests/index.js`), which builds a Deva from `tests/agent.json` and `tests/client.json`, runs it through the lifecycle and a self-test method, and prints the log. **It passes as long as nothing throws. There are no assertions yet.** Real assertion tests are planned.
310
+ This runs the assertion suite in `tests/suite/` with Node's built-in test runner (`node --test`), with no extra dependencies. GitHub Actions runs it on every push and pull request on Node 22 and 24, shown by the Tests badge at the top.
311
+
312
+ | File | Covers | Tests |
313
+ |---|---|---|
314
+ | `00-build.test.js` | Building a Deva | 1 |
315
+ | `01-init.test.js` | `init()` order and failures | 5 |
316
+ | `02-getters.test.js` | Getters and stamped copies | 31 |
317
+ | `03-hash.test.js` | The md5, sha256 and sha512 tiers | 6 |
318
+ | `04-license.test.js` | `license_check` | 6 |
319
+ | `05-messaging.test.js` | question, answer, ask and talk | 12 |
320
+ | `06-shutdown.test.js` | `stop()` and the shutdown chain | 8 |
321
+ | `07-help.test.js` | `help()` and feecting help files | 10 |
322
+
323
+ `tests/suite/_deva.js` builds a fresh test Deva from `tests/agent.json` and `tests/client.json`, and `tests/suite/help/` holds the sample `.feecting` files for the help tests. The full list with edge cases is at [deva.world/tests](https://deva.world/tests/).
324
+
325
+ `npm run demo` runs the older `tests/index.js` walkthrough, which builds a Deva, runs it through the lifecycle and prints the log.
270
326
 
271
327
  ## Method reference
272
328
 
@@ -293,6 +349,7 @@ These are the public methods.
293
349
  | `license_check(personalVLA, packageVLA)` | stamped approval or `false` | |
294
350
  | `load(key, client)` / `unload(key)` | Promise | Init or stop a child Deva in `devas`. |
295
351
  | `err(err, packet, reject?)` | — | See [Error handling](#error-handling). |
352
+ | `help(msg, help_dir)` | Promise of feecting text | See [Help](#help). |
296
353
 
297
354
  Not covered here because they weren't exercised for this README: `help(msg, help_dir)` (reads `<help_dir>/help/<file>.feecting` sections between `::BEGIN:<PART>` and `::END:<PART>`; feecting is Quinn Michaels' own language), `sign(packet)`, `machine()`, and the `lib` helpers (`this.lib.copy`, `formatDate`, and others).
298
355
 
package/_data/msgs.json CHANGED
@@ -23,7 +23,7 @@
23
23
  "asktimeout": "⛔️ ASK TIMEOUT",
24
24
  "noask": "⛔️ ASK TARGET NOT FOUND",
25
25
  "method_not_found": "⛔️ METHOD NOT FOUND",
26
- "help_not_found": "⛔️ HELP FILE NOT FOUND",
26
+ "help_not_found": "⛔️ HELP NOT FOUND",
27
27
  "invalid_agent": "⛔️ Agent Hash Invalid",
28
28
  "invalid_client": "⛔️ Client Hash Invalid",
29
29
  "personalVLA": "❌ Bad Personal VLA",
package/_data/tests.json CHANGED
@@ -50,6 +50,12 @@
50
50
  "title": "Shutdown",
51
51
  "describe": "stop() stops child Devas first, runs the full chain in order to onShutdown, clears features, answers pending asks offline and leaves nothing on the event bus.",
52
52
  "count": 8
53
+ },
54
+ {
55
+ "file": "07-help.test.js",
56
+ "title": "Help",
57
+ "describe": "help() returns the right feecting section by file and part, answers help not found for a missing file or section as invalid and bad without an error or a good intent, and answers offline before init and after stop.",
58
+ "count": 10
53
59
  }
54
60
  ],
55
61
  "edgecases": [
@@ -70,7 +76,13 @@
70
76
  "describe": "A parent's stop() now stops each child Deva through its full chain before the parent closes.",
71
77
  "suite": "06-shutdown.test.js",
72
78
  "fixed": "1.64.9"
73
- }
79
+ },
80
+ {
81
+ "title": "Missing help section",
82
+ "describe": "A missing section resolved help not found but kept going, threw, logged an error, and the finally block logged valid and good on both not-found paths.",
83
+ "suite": "07-help.test.js",
84
+ "fixed": "1.64.25"
85
+ }
74
86
  ]
75
87
  }
76
88
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "31711622713594414221",
3
3
  "name": "@indra.ai/deva",
4
- "version": "1.64.25",
4
+ "version": "1.64.26",
5
5
  "description": "Deva Core a Vedic-inspired Event Based Context Aware Feature, Zone, Action, and State Machine integrated Artificial Intelligence Framework",
6
6
  "main": "index.js",
7
7
  "license": "VLA:31711622713594414221 LICENSE.md",
@@ -0,0 +1,102 @@
1
+ "use strict";
2
+ // Deva Core Test Suite: step 7, the help system
3
+ // Copyright ©2000-2026 Quinn Michaels; All rights reserved.
4
+ // Owner Signature Required For Lawful Use.
5
+ // Distributed under VLA:31711622713594414221 LICENSE.md
6
+
7
+ import test from 'node:test';
8
+ import assert from 'node:assert/strict';
9
+ import {readFileSync} from 'node:fs';
10
+ import {join} from 'node:path';
11
+ import {build, client, info} from './_deva.js';
12
+
13
+ // help() reads <help_dir>/help/<file>.feecting, so the suite folder is the help_dir.
14
+ const DIR = info.dir;
15
+ const read = file => readFileSync(join(DIR, 'help', `${file}.feecting`), 'utf8');
16
+ // the exact text between ::BEGIN:<PART> and ::END:<PART>
17
+ const section = (file, part) => read(file).split(`::BEGIN:${part}`)[1].split(`::END:${part}`)[0];
18
+
19
+ // collect the error events and the help state and intent records during one help() call.
20
+ async function watch(deva, run) {
21
+ const seen = {error: 0, valid: 0, good: 0, invalid: [], bad: []};
22
+ const onError = () => seen.error++;
23
+ const onState = d => {
24
+ if (!d.text.includes('help:')) return;
25
+ if (d.value === 'valid') seen.valid++;
26
+ if (d.value === 'invalid') seen.invalid.push(d.text.split('help:')[1].split(':').slice(0, 2).join(':'));
27
+ };
28
+ const onIntent = d => {
29
+ if (!d.text.includes('help:')) return;
30
+ if (d.value === 'good') seen.good++;
31
+ if (d.value === 'bad') seen.bad.push(d.text.split('help:')[1].split(':').slice(0, 2).join(':'));
32
+ };
33
+ deva.events.on(deva._events.error, onError);
34
+ deva.events.on(deva._events.state, onState);
35
+ deva.events.on(deva._events.intent, onIntent);
36
+ try { seen.result = await run(); }
37
+ finally {
38
+ deva.events.removeListener(deva._events.error, onError);
39
+ deva.events.removeListener(deva._events.state, onState);
40
+ deva.events.removeListener(deva._events.intent, onIntent);
41
+ }
42
+ return seen;
43
+ }
44
+
45
+ test('help() answers offline before init()', async () => {
46
+ const deva = build();
47
+ assert.equal(await deva.help('main', DIR), deva._messages.offline);
48
+ });
49
+
50
+ test.describe('after init', () => {
51
+ const deva = build();
52
+ test.before(async () => { await deva.init(structuredClone(client)); });
53
+ test.after(async () => { await deva.stop(); });
54
+
55
+ test('an empty message returns the MAIN section of main.feecting', async () => {
56
+ assert.equal(await deva.help('', DIR), section('main', 'MAIN'));
57
+ });
58
+
59
+ test('main returns the MAIN section of main.feecting', async () => {
60
+ assert.equal(await deva.help('main', DIR), section('main', 'MAIN'));
61
+ });
62
+
63
+ test('file:part returns that part, matched in upper case', async () => {
64
+ assert.equal(await deva.help('main:ask', DIR), section('main', 'ASK'));
65
+ });
66
+
67
+ test('the file name picks the help file', async () => {
68
+ assert.equal(await deva.help('suite', DIR), section('suite', 'MAIN'));
69
+ });
70
+
71
+ test('only the first word of the message is used', async () => {
72
+ assert.equal(await deva.help('main:ask and more words', DIR), section('main', 'ASK'));
73
+ });
74
+
75
+ test('a found section records valid and good with no error', async () => {
76
+ const seen = await watch(deva, () => deva.help('main', DIR));
77
+ assert.equal(seen.result, section('main', 'MAIN'));
78
+ assert.deepEqual([seen.error, seen.valid, seen.good], [0, 1, 1]);
79
+ assert.deepEqual([seen.invalid, seen.bad], [[], []]);
80
+ });
81
+
82
+ test('a missing file answers help not found as invalid and bad, with no error and no valid or good', async () => {
83
+ const seen = await watch(deva, () => deva.help('nofile', DIR));
84
+ assert.equal(seen.result, deva._messages.help_not_found);
85
+ assert.deepEqual([seen.error, seen.valid, seen.good], [0, 0, 0]);
86
+ assert.deepEqual([seen.invalid, seen.bad], [['not:exists'], ['not:exists']]);
87
+ });
88
+
89
+ test('a missing section answers help not found as invalid and bad, with no error and no valid or good', async () => {
90
+ const seen = await watch(deva, () => deva.help('main:nopart', DIR));
91
+ assert.equal(seen.result, deva._messages.help_not_found);
92
+ assert.deepEqual([seen.error, seen.valid, seen.good], [0, 0, 0]);
93
+ assert.deepEqual([seen.invalid, seen.bad], [['not:found'], ['not:found']]);
94
+ });
95
+ });
96
+
97
+ test('help() answers offline after stop()', async () => {
98
+ const deva = build();
99
+ await deva.init(structuredClone(client));
100
+ await deva.stop();
101
+ assert.equal(await deva.help('main', DIR), deva._messages.offline);
102
+ });
@@ -0,0 +1,9 @@
1
+ ::BEGIN:MAIN
2
+ # Test Deva Help
3
+ p: The main help for the test Deva.
4
+ ::END:MAIN
5
+
6
+ ::BEGIN:ASK
7
+ ## Ask
8
+ p: Use #key method text to ask another Deva.
9
+ ::END:ASK
@@ -0,0 +1,4 @@
1
+ ::BEGIN:MAIN
2
+ # Suite Help
3
+ p: A second help file, so file selection can be tested.
4
+ ::END:MAIN