@prestack/thread 0.1.3 → 0.1.5

package/dist/integrations/target.js

@@ -1,52 +1,112 @@
-import { SECRECY, secrecyOf } from "./secret.js";
+import { join } from 'node:path';
+import { execPath } from 'node:process';
+import { SECRECY, secrecyOf } from './secret.js';
 export const REACH = {
     postgres: 'pg_',
     pglite: 'pl_',
     browser: 'zu_',
     https: 'ht_',
-    module: 'mod_',
     cli: 'cli_',
+    disk: 'dsk_',
+    sdk: 'sdk_',
+};
+export const ADDRESS = {
+    row: 'reached at the address written on its row, which anybody may read',
+    secret: 'reached at a secret, because its address is a connection string and a connection string carries a password',
+    nothing: 'addressed by nothing',
 };
 export const HOLDS = {
-    postgres: { takes: 'entities', from: 'server', addressed: true, arrives: null, migrations: true, references: true, sql: true, driver: 'postgres' },
-    pglite: { takes: 'entities', from: 'either', addressed: true, arrives: null, migrations: true, references: true, sql: true, driver: '@electric-sql/pglite' },
-    browser: { takes: 'entities', from: 'browser', addressed: false, arrives: null, migrations: false, references: false, sql: false, driver: 'zustand' },
-    https: { takes: 'calls', from: 'either', addressed: true, arrives: null, migrations: false, references: false, sql: false, driver: null },
-    module: { takes: 'names', from: 'either', addressed: false, arrives: 'npm', migrations: false, references: false, sql: false, driver: null },
-    cli: { takes: 'names', from: 'server', addressed: false, arrives: 'machine', migrations: false, references: false, sql: false, driver: null },
+    postgres: { takes: 'entities', from: 'server', addressed: 'secret', migrations: true, references: true, sql: true, driver: 'postgres' },
+    pglite: { takes: 'entities', from: 'either', addressed: 'nothing', migrations: true, references: true, sql: true, driver: '@electric-sql/pglite' },
+    browser: { takes: 'entities', from: 'browser', addressed: 'nothing', migrations: false, references: false, sql: false, driver: 'zustand' },
+    https: { takes: 'calls', from: 'either', addressed: 'row', migrations: false, references: false, sql: false, driver: null },
+    cli: { takes: 'calls', from: 'server', addressed: 'nothing', migrations: false, references: false, sql: false, driver: null },
+    disk: { takes: null, from: 'server', addressed: 'nothing', migrations: false, references: false, sql: false, driver: null },
+    sdk: { takes: 'calls', from: 'server', addressed: 'nothing', migrations: false, references: false, sql: false, driver: null },
 };
 export const SAID = {
     postgres: 'A postgres this app connects to over the network. It keeps entities and holds everything a declaration can state about their shape — tables, references and invariants — so what is kept here is held to that shape by the database itself rather than by whatever remembered to check. Who may touch a row is not asked of it: that is answered by the app, against the caller who actually arrived. It is reached from a server only: a connection to it from a page is a database somebody else can open. This is where a thing goes when losing it would matter.',
-    pglite: 'A postgres running inside the process that opened it. It keeps entities and holds tables, references and invariants, exactly as the networked one does — what differs is who can reach it, not what it can be told to hold. What belongs here is what the caller is already entitled to see: a local copy, a working set, an offline cache.',
+    pglite: 'A postgres running inside the process that opened it. It keeps entities and holds tables, references and invariants, exactly as the networked one does — what differs is who can reach it, not what it can be told to hold. It is addressed by nothing: its files sit under .thread beside the tree, in a folder named after the target, so nobody types a path and a fresh clone starts it empty. What belongs here is what the caller is already entitled to see: a local copy, a working set, an offline cache.',
     browser: 'A store in the browser, held in memory the viewer owns. It keeps entities and it is addressed by nothing, because it is already where the code runs. It holds no migration, because a page load builds it from nothing every time. What belongs here is what the interface needs to be responsive and can afford to lose.',
-    https: 'Something this app calls over https — a vendor, a service, another app. It accepts calls rather than entities: each is declared with the verb and the path it takes, so a node names the call and never writes a url. Its address and its credential are both secrets, and whether it may be reached from a browser is decided by which kind of secret it needs rather than by the reach itself.',
-    module: 'Something this app brings in from outside the repository and calls — an npm package, an SDK, an installer. Declaring one installs it and reads the methods it publishes, then asks which of them this app may call. What is picked is written down, and a method that is not on that list is refused before the package is imported: what can ever run is fixed when the target is declared, not by whoever calls it. A credential is named only if it needs one, and it comes from the vault at the moment of the call and is never written anywhere. A package you only import is a dependency rather than one of these, and the manifest already declares it.',
-    cli: 'A program this app runs as a command — git is the one that made this necessary. It is not installed, because it is not a dependency: it is either on the machine or it is not, and declaring one checks that it is there and says what to do when it is not. What it accepts is its subcommands, read off the program itself at the moment it is declared and written down: the whole surface the tool really has, because it was asked rather than typed, and a subcommand that is not on that list never runs. Declaring one is what brings `thread run <name>` into being, so the CLI grows a command by the app stating an integration rather than by anybody writing a verb — and an app that has not declared it has no such command at all.',
+    https: 'Something this app calls over https — a vendor, a service, another app. It accepts calls rather than entities: each is declared with the verb and the path it takes, so a node names the call and never writes a url. Where it is goes on its row as address, and a header every call carries goes on its row as headers, because both are facts anybody may read; a credential it sends is a secret, and requiring one is what keeps the target out of a browser.',
+    cli: 'A program this app runs as a command. git is the one that made this necessary. It is not installed, because it is not a dependency: it is on the machine or it is not, and a run finds out. What it accepts is the words it is asked with, declared beside it as calls with thread create target call: a subcommand where the program has them, and the option that selects what it does where it has none, each spelled the way the program spells it. A word that is not declared never runs. The program is the one the target is named after, so declaring one runs nothing and reads nothing off the machine. An operation that requires it is handed one function per declared word, and that is the only way this app ever runs it.',
+    disk: 'The disk this app runs on. It answers a fixed set of orders — is this there, read it, write it, list what is beside it, how big it is, remove it, and what it really is — and those orders are the same for every disk, because they are what a filesystem does rather than what any one of them chose to offer. None of them runs anything: a disk holds files and a program that installs packages is not a file order, which is why installing what a tree depends on happens where somebody typed the command and is not something a disk can be asked for. It is reached from a server only: a page has no filesystem. A trial stands one of these up out of its own scenario, so a rule can be measured against files that exist for the length of that run and nothing is written where you work.',
+    sdk: 'A package this app calls inside its own process — a vendor\'s SDK, fetched from npm, a git link or a tarball. It accepts calls rather than entities: the file this target declares exports `calls`, each call names the function there it runs as its path, and that file is the only place the package is imported, so an operation names the call and never the package. The integration it is part of names what to fetch in needs, and declaring the integration fetches it. It runs where the app runs, so it is addressed by nothing and reached from a server only.',
+};
+const on = (host, names) => names.map((one) => host + '.' + one);
+const driverOfReach = (one) => {
+    const driver = HOLDS[one].driver;
+    return driver === null ? [] : ['import ' + driver];
+};
+export const OPENS = {
+    postgres: driverOfReach('postgres'),
+    pglite: driverOfReach('pglite'),
+    browser: driverOfReach('browser'),
+    https: [
+        'fetch',
+        'XMLHttpRequest',
+        'WebSocket',
+        'EventSource',
+        ...on('window', ['fetch']),
+        ...on('navigator', ['sendBeacon']),
+        'import node:http',
+        'import node:https',
+        'import node:http2',
+        'import node:net',
+        'import node:tls',
+        'import node:dgram',
+        'import node:dns',
+    ],
+    cli: ['import node:child_process', 'import node:worker_threads', 'import node:cluster'],
+    disk: ['import node:fs', 'import node:fs/promises'],
+    sdk: [],
+};
+export const ORDERS = {
+    kind: 'kind',
+    read: 'read',
+    write: 'written',
+    list: 'list',
+    stat: 'stat',
+    remove: 'removed',
+    real: 'real',
+    fetch: 'fetched',
+    run: 'ran',
 };
+export function isRow(v) {
+    return typeof v === 'object' && v !== null && typeof v.id === 'string';
+}
+export function isTransactional(store) {
+    return typeof store.transaction === 'function';
+}
 export const CALL_PREFIX = 'cl_';
 const FILLED = /\{([a-z][a-z0-9_]*)\}/g;
 export const fills = (one) => [...one.path.matchAll(FILLED)].map((each) => each[1] ?? '');
 export function reachOf(id) {
     return Object.keys(REACH).find((one) => id.startsWith(REACH[one]));
 }
+export const standsHere = (one, targets) => !one.requires.some((each) => targets.some((two) => two.id === each));
 export function holdsOf(id) {
     const what = reachOf(id);
     return what === undefined ? undefined : HOLDS[what];
 }
+export function requirable(targets, calls) {
+    const declared = new Set(calls.map((one) => one.id));
+    return targets.filter((one) => holdsOf(one.id)?.takes !== 'calls' || one.takes.some((each) => declared.has(each)));
+}
 export function driverOf(id) {
     return holdsOf(id)?.driver ?? null;
 }
 export function addressOf(one, secrets) {
-    if (holdsOf(one.id)?.addressed !== true)
+    if (holdsOf(one.id)?.addressed !== 'secret')
         return undefined;
     const held = new Map(secrets.map((each) => [each.id, each]));
-    return one.requires.map((each) => held.get(each)).find((each) => each !== undefined && each.sends === undefined);
+    return one.requires.map((each) => held.get(each)).find((each) => each !== undefined && each.sends === undefined && each.signs === undefined);
 }
 export function credentialsOf(one, secrets) {
     const held = new Map(secrets.map((each) => [each.id, each]));
     return one.requires
         .map((each) => held.get(each))
-        .filter((each) => each !== undefined && each.sends !== undefined);
+        .filter((each) => each !== undefined && (each.sends !== undefined || each.signs !== undefined));
 }
 export function servesBrowser(one, secrets) {
     const holds = holdsOf(one.id);
@@ -73,23 +133,41 @@ export const unreachable = (targets) => targets
     .filter((one) => reachOf(one.id) === undefined)
     .map((one) => `\`${one.id}\` wears none of the prefixes a target is reached by (${Object.values(REACH).join(', ')}), so ` +
     'nothing can tell how to reach it — and how a thing is reached decides what may be declared for it');
+export const LOCKFILES = {
+    'pnpm-lock.yaml': 'pnpm',
+    'yarn.lock': 'yarn',
+    'bun.lockb': 'bun',
+    'package-lock.json': 'npm',
+};
+export const PACKAGER = 'packager';
+const NAMED = ['git', 'thread'];
+const RUNTIME = 'node';
+export const managerOf = (at, there) => Object.entries(LOCKFILES).find(([lock]) => there(join(at, lock)))?.[1] ?? 'npm';
+export function programOf(name, at, there) {
+    if (NAMED.includes(name))
+        return name;
+    if (name === RUNTIME)
+        return execPath;
+    if (name === PACKAGER)
+        return managerOf(at, there);
+    const installed = join(at, 'node_modules', '.bin', name);
+    return there(installed) ? installed : undefined;
+}
+export const unlisted = (name) => '`' + REACH.cli + name + '` names ' + name + ', and nothing lists a program by that name: it is not under node_modules/.bin, so this tree did not install it; it is not git, node or thread; and it is not `' + PACKAGER + '`, the word for whichever package manager the lockfile picks. A program the tree did not install is whatever the machine happens to have, and a target on that is a shell by another name. Add the package that provides it and declare the target again, or ask for it through a declared call on `' + REACH.cli + PACKAGER + '`';
 const SHAPED = {
-    module: /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/,
-    cli: /^[a-z][a-z0-9-]*$/,
+    cli: /^-{0,2}[A-Za-z][A-Za-z0-9-]*$/,
 };
 const EVERY_VALUE = new Set(['constructor', '__proto__', 'prototype']);
 export function misnamed(target, name) {
     const reach = reachOf(target);
-    if (reach !== 'module' && reach !== 'cli')
+    if (reach !== 'cli')
         return undefined;
     if (EVERY_VALUE.has(name)) {
-        return (`\`${name}\` is a step every JavaScript value has rather than something \`${target}\` offers, and walking to ` +
+        return (`\`${name}\` is a step every JavaScript value has rather than something \`${target}\` answers to, and walking to ` +
             'it leaves what was declared');
     }
     if (!SHAPED[reach].test(name)) {
-        return reach === 'module'
-            ? `\`${name}\` is not a method path — one name, or names joined by dots, e.g. \`customers.list\``
-            : `\`${name}\` is not a subcommand — one word as the program spells it, e.g. \`commit\` or \`rev-parse\``;
+        return name + ' is not one word as the program spells it. Give a subcommand, e.g. commit or rev-parse, or, where the program has none, the option that selects what it does, e.g. -p';
     }
     return undefined;
 }
@@ -106,10 +184,8 @@ export function misaccepted(targets, entities, calls) {
                 continue;
             if (holds.takes === 'calls' && isCall.has(named))
                 continue;
-            if (holds.takes === 'names') {
-                found.push(`\`${one.id}\` is reached as ${String(reachOf(one.id))} and its \`takes\` names "${named}" — what an ` +
-                    'installed package or a program responds to goes in `offers`, not here. `takes` is a demand, and the ' +
-                    'descent requires every word on one to be coined by a row in this tree; a method name never can be');
+            if (holds.takes === null) {
+                found.push(`\`${one.id}\` takes "${named}", and a ${String(reachOf(one.id))} takes nothing: it answers the orders every ${String(reachOf(one.id))} answers, stated once on the target itself`);
                 continue;
             }
             found.push(`\`${one.id}\` is reached over ${String(reachOf(one.id))} and so accepts ${holds.takes}, and its \`takes\` names ` +
@@ -118,6 +194,36 @@ export function misaccepted(targets, entities, calls) {
     }
     return found;
 }
+export const placedAt = (targets, id) => targets.find((one) => one.id === id)?.address ?? '';
+export function placed(one) {
+    const said = one.address;
+    if (said === undefined) {
+        return [one.id + ' is reached over https and its row says nothing about where. Give it an address: the absolute url every call on it is written from, scheme and host and nothing after the path'];
+    }
+    let held;
+    try {
+        held = new URL(said);
+    }
+    catch {
+        return [one.id + ' has the address ' + JSON.stringify(said) + ', and that is not an absolute url. Write the whole of it, scheme and host'];
+    }
+    if ([held.search, held.hash].some((each) => each !== '')) {
+        return [one.id + ' has the address ' + said + ', which carries a query or a fragment. Those belong to a call, so an address ends at its path'];
+    }
+    const wrong = Object.entries(one.headers ?? {}).filter(([, value]) => typeof value !== 'string');
+    if (wrong.length > 0) {
+        return [one.id + ' carries the header ' + String(wrong[0]?.[0] ?? '') + ' with a value that is not text. A header every call carries is written as text, exactly as it goes on the wire'];
+    }
+    return [];
+}
+const stated = (one, holds) => {
+    if (holds.addressed === 'row')
+        return placed(one);
+    const carried = [...(one.address === undefined ? [] : ['an address']), ...(one.headers === undefined ? [] : ['headers'])];
+    if (carried.length === 0)
+        return [];
+    return [one.id + ' carries ' + carried.join(' and ') + ', and a ' + String(reachOf(one.id)) + ' is ' + ADDRESS[holds.addressed] + '. Take it off the row'];
+};
 export function unaddressed(targets, secrets) {
     const held = new Map(secrets.map((one) => [one.id, one]));
     const found = [];
@@ -125,13 +231,14 @@ export function unaddressed(targets, secrets) {
         const holds = holdsOf(one.id);
         if (holds === undefined)
             continue;
+        found.push(...stated(one, holds));
         const addresses = one.requires
             .map((each) => held.get(each))
-            .filter((each) => each !== undefined && each.sends === undefined);
-        if (!holds.addressed) {
-            if (holds.arrives === null && addresses.length > 0) {
-                found.push(`\`${one.id}\` is reached over ${String(reachOf(one.id))}, which is addressed by nothing and needs nothing to ` +
-                    `reach it, and it requires \`${addresses[0]?.id ?? ''}\` — there is nowhere for that value to go`);
+            .filter((each) => each !== undefined && each.sends === undefined && each.signs === undefined);
+        if (holds.addressed !== 'secret') {
+            if (addresses.length > 0) {
+                found.push(one.id + ' is reached over ' + String(reachOf(one.id)) + ', which is ' + ADDRESS[holds.addressed] + ', and it requires ' +
+                    (addresses[0]?.id ?? '') + ', a secret with nowhere to be sent. A secret is a credential: give it the header it goes on with sends, or take it off this row');
             }
             continue;
         }
@@ -148,14 +255,15 @@ export function unaddressed(targets, secrets) {
     return found;
 }
 export function unheld(targets, secrets) {
-    const known = new Set(secrets.map((one) => one.id));
+    const known = new Set([...secrets.map((one) => one.id), ...targets.map((one) => one.id)]);
     const found = [];
     for (const one of targets) {
         for (const named of one.requires) {
             if (known.has(named))
                 continue;
-            found.push(`\`${one.id}\` requires "${named}", and this app declares no secret by that name. A secret is declared before it ` +
-                'is required, so the one place saying who may hold a value is never whichever place happened to need it');
+            found.push(`\`${one.id}\` requires "${named}", and this app declares no secret and no target by that name. A secret is declared before it ` +
+                'is required, and a target before it is reached through, so the one place saying who holds a value, or ' +
+                'answers for a reach, is never whichever place happened to need it');
         }
     }
     return found;
@@ -171,8 +279,22 @@ export function unanswered(calls, targets) {
         }
         const holds = holdsOf(of.id);
         if (holds !== undefined && holds.takes !== 'calls') {
-            found.push(`\`${one.id}\` is a call on \`${of.id}\`, which is reached over ${String(reachOf(of.id))} and keeps entities. ` +
-                'A place you keep rows in is not a place you issue verbs at');
+            found.push(holds.takes === 'entities'
+                ? `\`${one.id}\` is a call on \`${of.id}\`, which is reached over ${String(reachOf(of.id))} and keeps entities. A place you keep rows in is not a place you issue verbs at`
+                : `\`${one.id}\` is a call on \`${of.id}\`, which is a ${String(reachOf(of.id))} and answers the orders every ${String(reachOf(of.id))} answers, so nothing is declared on it. A node is handed those orders by requiring it`);
+            continue;
+        }
+        if (reachOf(of.id) === 'https' && one.method === undefined) {
+            found.push(`\`${one.id}\` is a call over https and states no method. A call over https says its verb: GET, POST, PUT, PATCH or DELETE`);
+            continue;
+        }
+        if (reachOf(of.id) !== 'https' && one.method !== undefined) {
+            found.push(`\`${one.id}\` states the method ${one.method}, and \`${of.id}\` is a ${String(reachOf(of.id))}. A subcommand or a method has no http verb, so take \`method\` off that row`);
+            continue;
+        }
+        const shaped = misnamed(of.id, one.path);
+        if (shaped !== undefined) {
+            found.push(`\`${one.id}\` is a call on \`${of.id}\`, and its path ${shaped}`);
             continue;
         }
         if (!of.takes.includes(one.id)) {
@@ -182,33 +304,32 @@ export function unanswered(calls, targets) {
     }
     return found;
 }
-export function misused(targets) {
+export function unplaced(targets, integrations) {
+    const known = new Set(integrations.map((one) => one.id));
     const found = [];
     for (const one of targets) {
-        const holds = holdsOf(one.id);
-        if (holds === undefined)
+        const named = one.of ?? '';
+        if (named === '') {
+            found.push(`\`${one.id}\` names no integration, and every target is one way into something outside this app — a vendor, ` +
+                'a service, a program on the machine. Say which one it reaches into: `thread create integration` lists ' +
+                'the ones already declared and declares another');
             continue;
-        if (holds.arrives !== null && (one.uses ?? '') === '') {
-            found.push(`\`${one.id}\` is reached as ${String(reachOf(one.id))} and does not say what it uses — ` +
-                `${holds.arrives === 'npm' ? 'the npm package to install' : 'the program to run'} goes in \`uses\`, because the ` +
-                'id is what this app calls it and not what it is');
-            continue;
-        }
-        if (holds.arrives === null && one.uses !== undefined) {
-            found.push(`\`${one.id}\` is reached over ${String(reachOf(one.id))}, where nothing is installed and nothing is spawned, ` +
-                `and it states \`uses: '${one.uses}'\` — there is nothing for that name to be`);
         }
+        if (known.has(named))
+            continue;
+        found.push(`\`${one.id}\` is part of "${named}", and this app declares no integration by that name. Declare it with ` +
+            '`thread create integration`, or point this row at one already declared');
     }
     return found;
 }
-export function refusals(targets, secrets, calls, entities) {
+export function refusals(targets, secrets, calls, entities, integrations) {
     return [
         ...unreachable(targets),
+        ...unplaced(targets, integrations),
         ...unheld(targets, secrets),
         ...unaddressed(targets, secrets),
         ...unanswered(calls, targets),
         ...misaccepted(targets, entities, calls),
-        ...misused(targets),
     ];
 }
 export function targetOf(entity, targets) {