@prestack/thread 0.1.3 → 0.1.5

package/dist/integrations/pglite.ts

@@ -0,0 +1,206 @@
+import type { Actor } from '../core/actor.ts'
+import type { FieldList, Row, Store } from './target.ts'
+
+const SHAPE = `
+  select table_name, column_name, data_type, is_nullable
+  from information_schema.columns
+  where table_schema = 'public'
+  order by table_name, column_name
+`
+
+const CONSTRAINTS = `
+  select tc.table_name, tc.constraint_type, kcu.column_name
+  from information_schema.table_constraints tc
+  left join information_schema.key_column_usage kcu on kcu.constraint_name = tc.constraint_name
+  where tc.table_schema = 'public'
+  order by tc.table_name, tc.constraint_type, kcu.column_name
+`
+
+interface Queried {
+  exec(sql: string): Promise<unknown>
+  query(sql: string, params?: readonly unknown[]): Promise<{ rows: readonly unknown[] }>
+  close(): Promise<void>
+}
+
+const MISSING =
+  'a postgres living inside this process needs `@electric-sql/pglite`, and it is not installed. No package here ' +
+  'declares it, because nothing needs one until a target is declared that keeps rows in one — install it in the ' +
+  'app that declares that target. Carrying on without having opened one would be the drift this exists to catch, ' +
+  'wearing a green tick'
+
+async function opened(at?: string): Promise<Queried> {
+  let made: { PGlite: new (at?: string) => Queried }
+  try {
+    made = (await import('@electric-sql/pglite')) as unknown as { PGlite: new (at?: string) => Queried }
+  } catch {
+    throw new Error(MISSING)
+  }
+  return new made.PGlite(at)
+}
+
+const APPLIED = '"_thread_applied"'
+
+async function caughtUp(made: Queried, history: readonly { readonly name: string; readonly sql: string }[]): Promise<void> {
+  if (history.length === 0) return
+  await made.exec('create table if not exists ' + APPLIED + ' ("name" text primary key)')
+  const done = new Set(
+    (await made.query('select "name" from ' + APPLIED)).rows.map((one) => String((one as { readonly name?: unknown }).name)),
+  )
+  for (const one of history) {
+    if (done.has(one.name)) continue
+    await made.exec(one.sql)
+    await made.query('insert into ' + APPLIED + ' ("name") values ($1)', [one.name])
+  }
+}
+
+export async function shapeOf(sql: readonly string[]): Promise<string> {
+  const db = await opened()
+  try {
+    for (const one of sql) await db.exec(one)
+    const columns = await db.query(SHAPE)
+    const constraints = await db.query(CONSTRAINTS)
+    return JSON.stringify({ columns: columns.rows, constraints: constraints.rows }, null, 2)
+  } finally {
+    await db.close()
+  }
+}
+
+export interface Kept {
+
+  readonly name: string
+
+  readonly schema: string
+
+  readonly tables: Readonly<Record<string, string>>
+
+  readonly address: Readonly<Record<string, string>>
+
+  readonly columns: Readonly<Record<string, readonly string[]>>
+
+  readonly at: string
+
+  readonly migrations?: readonly { readonly name: string; readonly sql: string }[]
+}
+
+export interface Stood {
+
+  readonly keeps: readonly string[]
+
+  readonly store: Store
+
+  seed(actor: Actor, rows: readonly { readonly entity: string; readonly row: Row }[]): Promise<void>
+
+  taken(actor: Actor): Promise<Readonly<Record<string, readonly Row[]>>>
+}
+
+export function standing(held: Omit<Kept, 'at'>): Stood {
+  const store = storing({ ...held, at: 'memory://', migrations: [] })
+  const keeps = Object.keys(held.tables)
+  return {
+    keeps,
+    store,
+    async seed(actor, rows) {
+      for (const one of rows) await store.insert(actor, one.entity, one.row)
+    },
+    async taken(actor) {
+      const found: Record<string, readonly Row[]> = {}
+      for (const entity of keeps) found[entity] = await store.list(actor, entity)
+      return found
+    },
+  }
+}
+
+export function storing(held: Kept): Store {
+  const q = (name: string): string => JSON.stringify(name)
+  const rowOf = (one: unknown): Row => one as Row
+  const known = (entity: string): readonly string[] => held.columns[entity] ?? []
+
+  const tableFor = (entity: string): string => {
+    const found = held.tables[entity]
+    if (found === undefined) throw new Error(entity + ' is not kept in ' + held.name + ', so it has no table here')
+    return found
+  }
+
+  const addressOf = (entity: string): string => {
+    const found = held.address[entity]
+    if (found === undefined) {
+      throw new Error(
+        entity + ' declares nothing that identifies one of its rows, so a row of it cannot be addressed here. ' +
+          'Give it a value and say so with `thread create entity edit`.',
+      )
+    }
+    return found
+  }
+
+  let opening: Promise<Queried> | undefined
+
+  const db = async (): Promise<Queried> => {
+    opening ??= (async () => {
+      const made = await opened(held.at)
+      await caughtUp(made, held.migrations ?? [])
+      await made.exec(held.schema)
+      return made
+    })()
+    return await opening
+  }
+
+  return {
+    async insert(_actor, entity, row) {
+      const cols = known(entity)
+      const taken = cols.filter((one) => (row as Record<string, unknown>)[one] !== undefined)
+      const answered = await (await db()).query(
+        'insert into ' + q(tableFor(entity)) + ' (' + taken.map(q).join(', ') + ') values (' +
+          taken.map((_, at) => '$' + String(at + 1)).join(', ') + ') returning *',
+        taken.map((one) => (row as Record<string, unknown>)[one]),
+      )
+      return rowOf(answered.rows[0])
+    },
+
+    async get(_actor, entity, key, fields: FieldList) {
+      const cols = known(entity)
+      const asked = fields.filter((one) => cols.includes(one as string)).map((one) => String(one))
+      const answered = await (await db()).query(
+        'select ' + (asked.length === 0 ? '*' : asked.map(q).join(', ')) + ' from ' + q(tableFor(entity)) +
+          ' where ' + q(addressOf(entity)) + ' = $1 limit 1',
+        [key],
+      )
+      return answered.rows.length === 0 ? null : rowOf(answered.rows[0])
+    },
+
+    async list(_actor, entity, opts) {
+      const cols = known(entity)
+      const asked = Object.entries(opts?.where ?? {}).filter(([one]) => cols.includes(one))
+      const answered = await (await db()).query(
+        'select * from ' + q(tableFor(entity)) +
+          (asked.length === 0 ? '' : ' where ' + asked.map(([one], at) => q(one) + ' = $' + String(at + 1)).join(' and ')) +
+          (opts?.limit === undefined ? '' : ' limit ' + String(opts.limit)),
+        asked.map(([, one]) => one),
+      )
+      return answered.rows.map(rowOf)
+    },
+
+    async update(_actor, entity, key, patch, expectedVersion) {
+      if (expectedVersion !== undefined) {
+        throw new Error(
+          held.name + ' keeps what ' + entity + ' declares and nothing else, so there is no version on a row to ' +
+            'check an expected one against. Declare a value for it and compare that, or update without a version.',
+        )
+      }
+      const cols = known(entity)
+      const taken = Object.entries(patch).filter(([one]) => cols.includes(one))
+      if (taken.length === 0) throw new Error('nothing in this patch is a value ' + entity + ' declares')
+      const answered = await (await db()).query(
+        'update ' + q(tableFor(entity)) + ' set ' +
+          taken.map(([one], at) => q(one) + ' = $' + String(at + 1)).join(', ') +
+          ' where ' + q(addressOf(entity)) + ' = $' + String(taken.length + 1) + ' returning *',
+        [...taken.map(([, one]) => one), key],
+      )
+      if (answered.rows.length === 0) throw new Error('record ' + String(key) + ' not found')
+      return rowOf(answered.rows[0])
+    },
+
+    async remove(_actor, entity, key) {
+      await (await db()).query('delete from ' + q(tableFor(entity)) + ' where ' + q(addressOf(entity)) + ' = $1', [key])
+    },
+  }
+}

package/dist/integrations/secret.d.ts

@@ -1,14 +1,20 @@
 import type { Member } from '../core/thread.ts';
 export declare const SECRECY: {
-    readonly server: "sec_";
-    readonly public: "pub_";
+    readonly server: 'sec_';
 };
 export declare const SAID: Readonly<Record<keyof typeof SECRECY, string>>;
+export interface Vault {
+    resolve(refs: readonly string[]): Promise<Readonly<Record<string, string>>>;
+}
 export interface Secret extends Member {
     readonly sends?: {
         readonly header: string;
         readonly prefix?: string;
     };
+    readonly signs?: {
+        readonly header: string;
+        readonly prefix?: string;
+    };
 }
 export declare function secrecyOf(id: string): keyof typeof SECRECY | undefined;
 export declare const isServerOnly: (id: string) => boolean;

package/dist/integrations/secret.js

@@ -1,10 +1,8 @@
 export const SECRECY = {
     server: 'sec_',
-    public: 'pub_',
 };
 export const SAID = {
-    server: 'A value only a server may ever hold — an API key, a connection string, a signing secret. Everything a browser bundle reaches is in the bundle and belongs to whoever opens the page, so a target requiring one of these is refused a browser entry when it is built rather than when somebody reads it.',
-    public: 'A value that may reach a browser: a base url, a publishable key, a project id. It is still a secret and still lives in the sealed store, because it still differs between a sandbox and production and nothing else here keeps that difference. What it is not is a thing that has to be withheld.',
+    server: 'A value only a server may ever hold: an API key, a connection string, a signing key. Every secret is one of these. A value anybody may read is not a secret and is never sealed — the address of a place this app calls and a header every call carries are written on the target row, and only a credential goes into the vault. Everything a browser bundle reaches is in the bundle and belongs to whoever opens the page, so a target requiring a secret is refused a browser entry when it is built rather than when somebody reads it.',
 };
 export function secrecyOf(id) {
     return Object.keys(SECRECY).find((one) => id.startsWith(SECRECY[one]));
@@ -12,8 +10,8 @@ export function secrecyOf(id) {
 export const isServerOnly = (id) => secrecyOf(id) === 'server';
 export const unclassified = (secrets) => secrets
     .filter((one) => secrecyOf(one.id) === undefined)
-    .map((one) => `\`${one.id}\` wears neither \`${SECRECY.server}\` nor \`${SECRECY.public}\`, so nothing can tell whether it may ` +
-    'reach a browser — and that prefix is the only thing standing between a server credential and a bundle');
+    .map((one) => one.id + ' does not wear ' + SECRECY.server + ', and every secret does: that prefix says only a server may ever hold the value. ' +
+    'A value anybody may read is not a secret. Write it on the row that needs it, as the address of a target or a header every call carries, and take this row out');
 const VALUED = ['value', 'secret', 'key', 'token', 'password', 'env'];
 export const valued = (secrets) => {
     const found = [];

package/dist/integrations/secret.ts

@@ -2,19 +2,23 @@ import type { Member } from '../core/thread.ts'
 
 export const SECRECY = {
   server: 'sec_',
-  public: 'pub_',
 } as const satisfies Readonly<Record<string, string>>
 
 export const SAID: Readonly<Record<keyof typeof SECRECY, string>> = {
   server:
-    'A value only a server may ever hold — an API key, a connection string, a signing secret. Everything a browser bundle reaches is in the bundle and belongs to whoever opens the page, so a target requiring one of these is refused a browser entry when it is built rather than when somebody reads it.',
-  public:
-    'A value that may reach a browser: a base url, a publishable key, a project id. It is still a secret and still lives in the sealed store, because it still differs between a sandbox and production and nothing else here keeps that difference. What it is not is a thing that has to be withheld.',
+    'A value only a server may ever hold: an API key, a connection string, a signing key. Every secret is one of these. A value anybody may read is not a secret and is never sealed — the address of a place this app calls and a header every call carries are written on the target row, and only a credential goes into the vault. Everything a browser bundle reaches is in the bundle and belongs to whoever opens the page, so a target requiring a secret is refused a browser entry when it is built rather than when somebody reads it.',
+}
+
+export interface Vault {
+
+  resolve(refs: readonly string[]): Promise<Readonly<Record<string, string>>>
 }
 
 export interface Secret extends Member {
 
   readonly sends?: { readonly header: string; readonly prefix?: string }
+
+  readonly signs?: { readonly header: string; readonly prefix?: string }
 }
 
 export function secrecyOf(id: string): keyof typeof SECRECY | undefined {
@@ -28,8 +32,8 @@ export const unclassified = (secrets: readonly Secret[]): readonly string[] =>
     .filter((one) => secrecyOf(one.id) === undefined)
     .map(
       (one) =>
-        `\`${one.id}\` wears neither \`${SECRECY.server}\` nor \`${SECRECY.public}\`, so nothing can tell whether it may ` +
-        'reach a browser — and that prefix is the only thing standing between a server credential and a bundle',
+          one.id + ' does not wear ' + SECRECY.server + ', and every secret does: that prefix says only a server may ever hold the value. ' +
+          'A value anybody may read is not a secret. Write it on the row that needs it, as the address of a target or a header every call carries, and take this row out',
     )
 
 const VALUED = ['value', 'secret', 'key', 'token', 'password', 'env']

package/dist/integrations/target.d.ts

@@ -1,19 +1,26 @@
 import type { Member } from '../core/thread.ts';
+import type { Actor } from '../core/actor.ts';
 import { type Secret } from './secret.ts';
 export declare const REACH: {
-    readonly postgres: "pg_";
-    readonly pglite: "pl_";
-    readonly browser: "zu_";
-    readonly https: "ht_";
-    readonly module: "mod_";
-    readonly cli: "cli_";
+    readonly postgres: 'pg_';
+    readonly pglite: 'pl_';
+    readonly browser: 'zu_';
+    readonly https: 'ht_';
+    readonly cli: 'cli_';
+    readonly disk: 'dsk_';
+    readonly sdk: 'sdk_';
 };
 export type Reach = keyof typeof REACH;
+export declare const ADDRESS: {
+    readonly row: 'reached at the address written on its row, which anybody may read';
+    readonly secret: 'reached at a secret, because its address is a connection string and a connection string carries a password';
+    readonly nothing: 'addressed by nothing';
+};
+export type Addressed = keyof typeof ADDRESS;
 export interface Holds {
-    readonly takes: 'entities' | 'calls' | 'names';
+    readonly takes: 'entities' | 'calls' | null;
     readonly from: 'server' | 'browser' | 'either';
-    readonly addressed: boolean;
-    readonly arrives: 'npm' | 'machine' | null;
+    readonly addressed: Addressed;
     readonly migrations: boolean;
     readonly references: boolean;
     readonly sql: boolean;
@@ -21,31 +28,165 @@ export interface Holds {
 }
 export declare const HOLDS: Readonly<Record<Reach, Holds>>;
 export declare const SAID: Readonly<Record<Reach, string>>;
+export declare const OPENS: Readonly<Record<Reach, readonly string[]>>;
+export type Kind = 'file' | 'folder' | 'other' | 'none';
+export interface Listed {
+    readonly name: string;
+    readonly kind: Exclude<Kind, 'none'>;
+}
+export interface Measured {
+    readonly size: number;
+    readonly modified: number;
+}
+export interface Answering {
+    readonly kind: (at: string) => Kind;
+    readonly read: (at: string) => string;
+    readonly write: (at: string, said: string, mode?: number) => void;
+    readonly list: (at: string) => readonly Listed[];
+    readonly stat: (at: string) => Measured;
+    readonly remove: (at: string) => void;
+    readonly real: (at: string) => string;
+}
+export interface Attached extends Answering {
+    readonly fetch: (at: string) => string;
+    readonly run: (at: string, words: readonly string[]) => Ran;
+}
+export declare const ORDERS: {
+    readonly kind: 'kind';
+    readonly read: 'read';
+    readonly write: 'written';
+    readonly list: 'list';
+    readonly stat: 'stat';
+    readonly remove: 'removed';
+    readonly real: 'real';
+    readonly fetch: 'fetched';
+    readonly run: 'ran';
+};
+export interface Order {
+    readonly order: keyof typeof ORDERS;
+    readonly at: string;
+    readonly said?: string;
+    readonly mode?: number;
+    readonly words?: readonly string[];
+}
+export interface Answer {
+    readonly answered: string;
+    readonly found?: unknown;
+    readonly said?: string;
+    readonly at?: string;
+    readonly because?: string;
+}
+export interface Recorded {
+    readonly order: Order;
+    readonly answered: Answer;
+}
+export interface How {
+    readonly at?: string;
+    readonly hears?: string;
+    readonly of?: string;
+    readonly answered?: readonly Answer[];
+    readonly recording?: readonly Recorded[];
+    readonly answering?: number;
+}
+export interface Ran {
+    readonly there: boolean;
+    readonly ok: boolean;
+    readonly code: number;
+    readonly out: string;
+    readonly err: string;
+    readonly killed: string | null;
+    readonly why: string;
+    readonly of?: string;
+    readonly asks?: readonly Order[];
+    readonly lost?: string;
+}
+export type Running<C extends string = string> = Readonly<Record<C, (args: readonly string[], shows?: boolean | 'errors' | 'tee', within?: number, how?: How) => Promise<Ran>>>;
+export type Calling<C extends string = string> = {
+    readonly [K in C]: (given?: unknown) => Promise<unknown>;
+};
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface HttpRequest {
+    readonly target: string;
+    readonly address: string;
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: Uint8Array;
+    readonly contentType?: string;
+    readonly idempotencyKey?: string;
+    readonly told?: (said: unknown) => void;
+}
+export interface HttpResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: Uint8Array;
+}
+export interface Http {
+    call(request: HttpRequest, within?: number): Promise<HttpResponse>;
+}
+export type Row = Record<string, unknown>;
+export type PropertyValue = string | number | boolean | null | readonly (string | number | boolean)[];
+export declare function isRow(v: unknown): v is Row;
+export type ReadField = `fld_${string}` | `rel_${string}` | (string & {});
+export type FieldList = readonly [ReadField, ...ReadField[]];
+export interface Store {
+    insert(actor: Actor, entity: string, row: Row): Promise<Row>;
+    get(actor: Actor, entity: string, key: string | number, fields: FieldList): Promise<Row | null>;
+    list(actor: Actor, entity: string, opts?: {
+        limit?: number;
+        where?: Readonly<Record<string, string | number | boolean | null>>;
+    }): Promise<Row[]>;
+    update(actor: Actor, entity: string, key: string | number, patch: Record<string, unknown>, expectedVersion?: number): Promise<Row>;
+    remove(actor: Actor, entity: string, key: string | number): Promise<void>;
+}
+export interface Transactional {
+    transaction<T>(actor: Actor, fn: () => Promise<T>): Promise<T>;
+}
+export declare function isTransactional(store: Store): store is Store & Transactional;
+export interface Integration extends Member {
+    readonly needs?: Readonly<Record<string, string>>;
+}
 export interface Target extends Member {
+    readonly of: string;
     readonly takes: readonly string[];
     readonly requires: readonly string[];
-    readonly uses?: string;
-    readonly offers?: readonly string[];
+    readonly address?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface Webhook extends Member {
+    readonly of: string;
+    readonly path: string;
+    readonly arrives?: string;
+    readonly invokes: string;
 }
 export interface Call extends Member {
     readonly of: string;
-    readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     readonly path: string;
 }
 export declare const CALL_PREFIX = "cl_";
 export declare const fills: (one: Call) => readonly string[];
 export declare function reachOf(id: string): Reach | undefined;
+export declare const standsHere: (one: Target, targets: readonly Target[]) => boolean;
 export declare function holdsOf(id: string): Holds | undefined;
+export declare function requirable(targets: readonly Target[], calls: readonly Call[]): readonly Target[];
 export declare function driverOf(id: string): string | null;
 export declare function addressOf(one: Target, secrets: readonly Secret[]): Secret | undefined;
 export declare function credentialsOf(one: Target, secrets: readonly Secret[]): readonly Secret[];
 export declare function servesBrowser(one: Target, secrets: readonly Secret[]): true | string;
 export declare const unreachable: (targets: readonly Target[]) => readonly string[];
+export declare const LOCKFILES: Readonly<Record<string, string>>;
+export declare const PACKAGER = "packager";
+export declare const managerOf: (at: string, there: (path: string) => boolean) => string;
+export declare function programOf(name: string, at: string, there: (path: string) => boolean): string | undefined;
+export declare const unlisted: (name: string) => string;
 export declare function misnamed(target: string, name: string): string | undefined;
 export declare function misaccepted(targets: readonly Target[], entities: readonly string[], calls: readonly Call[]): readonly string[];
+export declare const placedAt: (targets: readonly Target[], id: string) => string;
+export declare function placed(one: Target): readonly string[];
 export declare function unaddressed(targets: readonly Target[], secrets: readonly Secret[]): readonly string[];
 export declare function unheld(targets: readonly Target[], secrets: readonly Secret[]): readonly string[];
 export declare function unanswered(calls: readonly Call[], targets: readonly Target[]): readonly string[];
-export declare function misused(targets: readonly Target[]): readonly string[];
-export declare function refusals(targets: readonly Target[], secrets: readonly Secret[], calls: readonly Call[], entities: readonly string[]): readonly string[];
+export declare function unplaced(targets: readonly Target[], integrations: readonly Integration[]): readonly string[];
+export declare function refusals(targets: readonly Target[], secrets: readonly Secret[], calls: readonly Call[], entities: readonly string[], integrations: readonly Integration[]): readonly string[];
 export declare function targetOf(entity: string, targets: readonly Target[]): Target | string;