@defdone/annon 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/node/output/text.js

@@ -0,0 +1,43 @@
+/** Shared pieces of the human output: safe text, short IDs, aligned tables and field lists. */
+/**
+ * Text from a shop, a catalog or a host is untrusted. Control characters (terminal escapes) and
+ * bidirectional overrides are replaced before it reaches a terminal; `lines` keeps newlines.
+ */
+const BIDI = /[\u202a-\u202e\u2066-\u2069]/g;
+export function cleanText(value, lines = false) {
+    const text = String(value).replace(BIDI, '');
+    return lines
+        ? // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are the target
+            text.replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/g, ' ')
+        : // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are the target
+            text.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ');
+}
+/** `0x1234abcd...ef01` for a long ID or address; short values are returned whole. */
+export const short = (id) => (id.length > 20 ? `${id.slice(0, 10)}...${id.slice(-4)}` : id);
+export const truncate = (text, max) => text.length > max ? `${text.slice(0, max - 3)}...` : text;
+/** Left-aligned columns, two spaces apart; the last column is not padded. */
+export function table(rows) {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => {
+            widths[i] = Math.max(widths[i] ?? 0, cell.length);
+        });
+    return rows
+        .map((row) => row
+        .map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i] ?? 0)))
+        .join('  ')
+        .trimEnd())
+        .join('\n');
+}
+/** Every field of a result as `name: value`, so a command without its own layout hides nothing. */
+export function fields(result) {
+    return Object.entries(result)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${key}: ${cleanText(value !== null && typeof value === 'object' ? JSON.stringify(value) : value)}`)
+        .join('\n');
+}
+export const networkName = (network) => network === 'near:mainnet'
+    ? 'NEAR mainnet'
+    : network === 'near:testnet'
+        ? 'NEAR testnet'
+        : network;

package/dist/node/purchase-commands.js

@@ -12,6 +12,7 @@ import { backupPath, fail, isId } from './adapter-checks.js';
 import { AdapterError, publicError, usage } from './errors.js';
 import { fileSource, newOutput, withOutput, withSpool } from './io.js';
 import { resourceHeader } from './offers.js';
+import { rememberPurchase } from './purchase-ref.js';
 import { resourceAllowed } from './resources.js';
 import { retryGate } from './retry-gate.js';
 import { readBackupSecret } from './wallets.js';
@@ -94,6 +95,9 @@ async function recover(ctx) {
         wallet: await wallet(),
         ...(o.purchase ? { purchaseId: o.purchase } : {}),
     });
+    // Recovered purchases can be named by an ID prefix under this contract; the latest stays as is.
+    for (const r of recovered)
+        await rememberPurchase(c, r.purchase_id, false);
     return {
         errors,
         recovered: recovered.map((r) => ({

package/dist/node/purchase-ref.d.ts

@@ -0,0 +1,15 @@
+import type { Input } from './cli.js';
+import type { Config } from './config.js';
+/** IDs of the records saved in a store directory. They are stored in the clear; no secret is read. */
+export declare function savedRecordIds(storeDir: string): Promise<string[]>;
+/**
+ * Lists a purchase ID under the configured deployment, and with `latest` makes it the purchase
+ * `status` and `open` mean without an ID. `buy` calls it before the purchase record is saved, so a
+ * paid purchase is always listed and the latest; `recover` lists what it recovered.
+ */
+export declare function rememberPurchase(c: Config, purchaseId: string, latest?: boolean): Promise<void>;
+/**
+ * Fills in the purchase `status` or `open` refers to. A name of 8 to 63 hex digits is always read
+ * as an ID prefix; write a file with such a name as `./name`.
+ */
+export declare function withPurchaseRef(o: Input, c: Config): Promise<Input>;

package/dist/node/purchase-ref.js

@@ -0,0 +1,93 @@
+/** How `status` and `open` name a saved purchase without its full ID: the latest one, or a prefix. */
+import { mkdir, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileStore } from '../pay/store-node.js';
+import { fail, isId } from './adapter-checks.js';
+const LATEST = 'latest-purchase';
+const latestStore = (c) => fileStore(join(c.stateDir, LATEST));
+/** One entry per deployment, so another contract's or network's purchase is never picked up. */
+const latestKey = (c) => JSON.stringify([c.network, c.contractId]);
+/** IDs of the records saved in a store directory. They are stored in the clear; no secret is read. */
+export async function savedRecordIds(storeDir) {
+    let names;
+    try {
+        names = await readdir(storeDir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const ids = [];
+    for (const name of names) {
+        if (!/^[0-9a-f]{64}\.json$/.test(name))
+            continue;
+        ids.push(JSON.parse(await readFile(join(storeDir, name), 'utf8')).id);
+    }
+    return ids;
+}
+/**
+ * Lists a purchase ID under the configured deployment, and with `latest` makes it the purchase
+ * `status` and `open` mean without an ID. `buy` calls it before the purchase record is saved, so a
+ * paid purchase is always listed and the latest; `recover` lists what it recovered.
+ */
+export async function rememberPurchase(c, purchaseId, latest = true) {
+    await mkdir(join(c.stateDir, LATEST), { recursive: true, mode: 0o700 });
+    const store = latestStore(c);
+    const id = latestKey(c);
+    // Another command of the same deployment may write in between; adding an ID is safe to repeat.
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const before = await store.load(id);
+        const ids = before?.ids ?? [];
+        const pointer = latest ? purchaseId : before?.purchaseId;
+        if (ids.includes(purchaseId) && pointer === before?.purchaseId)
+            return;
+        const next = {
+            id,
+            revision: (before?.revision ?? -1) + 1,
+            ...(pointer === undefined ? {} : { purchaseId: pointer }),
+            ids: ids.includes(purchaseId) ? ids : [...ids, purchaseId],
+        };
+        if (await store.compareAndSet(id, before, next))
+            return;
+    }
+    throw new Error('latest purchase conflict');
+}
+const PREFIX = /^(0x)?[0-9a-f]{8,63}$/;
+async function resolve(c, ref) {
+    if (ref === undefined) {
+        const latest = await latestStore(c).load(latestKey(c));
+        return (latest?.purchaseId ??
+            fail('purchase_required', 'No purchase has been saved by buy for this contract yet. Pass a purchase ID.', 2));
+    }
+    if (isId(ref) || !PREFIX.test(ref))
+        return ref;
+    const prefix = ref.startsWith('0x') ? ref : `0x${ref}`;
+    const saved = new Set((await savedRecordIds(join(c.stateDir, 'records')))
+        .map((id) => id.replace(/^recovery:/, ''))
+        .filter((id) => isId(id) && id.startsWith(prefix)));
+    // A saved record does not say in the clear which deployment it belongs to, and an ID says
+    // nothing about it. Only the IDs listed for this network and contract can be shortened.
+    const listed = new Set((await latestStore(c).load(latestKey(c)))?.ids ?? []);
+    const matches = [...saved].filter((id) => listed.has(id));
+    if (matches.length > 1)
+        return fail('purchase_required', 'This ID prefix matches more than one saved purchase. Use more digits.', 2);
+    const [only] = matches;
+    if (only)
+        return only;
+    return fail('purchase_required', saved.size > 0
+        ? 'A saved purchase starts with this ID prefix, but it is not listed for this contract and network. It was saved by an older version or for another contract or network. Use the full purchase ID.'
+        : 'No saved purchase starts with this ID prefix.', 2);
+}
+/**
+ * Fills in the purchase `status` or `open` refers to. A name of 8 to 63 hex digits is always read
+ * as an ID prefix; write a file with such a name as `./name`.
+ */
+export async function withPurchaseRef(o, c) {
+    if (o.command === 'open' && o.purchase !== undefined) {
+        const purchase = await resolve(c, o.purchase);
+        return purchase === undefined ? o : { ...o, purchase };
+    }
+    const target = await resolve(c, o.target);
+    return target === undefined ? o : { ...o, target };
+}

package/dist/node/shell/complete.d.ts

@@ -0,0 +1,2 @@
+export declare const sessionWords: string[];
+export declare function complete(line: string): [string[], string];

package/dist/node/shell/complete.js

@@ -0,0 +1,17 @@
+import { commandFlags, commandNames } from '../cli-flags.js';
+export const sessionWords = ['help', 'exit', 'quit'];
+export function complete(line) {
+    const words = line.trimStart().split(/\s+/);
+    const last = words.at(-1) ?? '';
+    const [first = ''] = words[0] === 'annon' ? words.slice(1) : words;
+    const typingCommand = words.length === (words[0] === 'annon' ? 2 : 1);
+    const choices = typingCommand
+        ? [...commandNames, ...sessionWords]
+        : first === 'shop' && words.at(-2) === 'shop'
+            ? ['add']
+            : last.startsWith('-') && commandNames.includes(first)
+                ? commandFlags(first)
+                : [];
+    const hits = choices.filter((choice) => choice.startsWith(last)).sort();
+    return [hits.map((hit) => `${hit} `), last];
+}

package/dist/node/shell/session.d.ts

@@ -0,0 +1,20 @@
+import type { Readable, Writable } from 'node:stream';
+import { type Input } from '../cli.js';
+import type { Dependencies } from '../command-context.js';
+type Execute = (input: Input) => Promise<Record<string, unknown>>;
+export interface SessionOptions {
+    input: Readable;
+    output: Writable;
+    /** Line editing and Tab completion; off for a plain stream. */
+    terminal?: boolean;
+    welcome: string;
+    /** Builds the adapter with the session's prompt and notices. */
+    adapter: (hooks: Pick<Dependencies, 'prompt' | 'notify'>) => Execute;
+    wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export declare function createSession(o: SessionOptions): {
+    /** Resolves with the exit code once the person leaves: 0, or 130 after a confirmed Ctrl-C. */
+    run(): Promise<number>;
+    interrupt: () => Promise<void>;
+};
+export {};

package/dist/node/shell/session.js

@@ -0,0 +1,219 @@
+/**
+ * The interactive session: one prompt, the one-shot commands without the `annon` prefix. Every
+ * line goes through `runCli` and the adapter exactly as a one-shot command does; the session adds
+ * the prompt, a memory of the last catalog listing, and Ctrl-C handling. It keeps no config, wallet,
+ * secret or purchase between commands: `status` and `open` without an ID reach the adapter as
+ * typed, and it finds the latest purchase saved for the contract and network of that line.
+ */
+import { createInterface } from 'node:readline/promises';
+import { isRow } from '../adapter-checks.js';
+import { runCli } from '../cli.js';
+import { AdapterError, publicError } from '../errors.js';
+import { rowNumber } from '../output/discovery.js';
+import { humanError } from '../output/human.js';
+import { cleanText } from '../output/text.js';
+import { complete } from './complete.js';
+import { splitWords } from './words.js';
+/** Commands that can move money or send a transaction; leaving in the middle needs a yes. */
+const paying = ['buy', 'fund', 'sell', 'share', 'stop', 'recover'];
+/** Commands that only read: Ctrl-C drops their result and returns to the prompt. */
+const reading = ['shops', 'catalog', 'status', 'verify', 'budget'];
+const HELP = `Commands work as on the command line, without the annon prefix:
+  login                      sign in with a browser wallet
+  shops, shop add <url>      list and add shops
+  catalog [--shop <id>]      list a shop's files, numbered
+  buy <#|url> [--open <file>]  buy a row of the last catalog, or a URL
+  status [id]                check a purchase (default: the latest saved for this contract)
+  open [id] --output <file>  save a bought file (default: the same latest purchase)
+  init, verify, recover, sell, share, fund, budget, stop
+  <command> --help           every command and option
+  exit, quit or Ctrl-D       leave
+  Ctrl-C                     answers a prompt with no, drops a listing or status result, stops
+                             a wait for acceptance, and asks before leaving a running payment`;
+export function createSession(o) {
+    const rl = createInterface({
+        input: o.input,
+        output: o.output,
+        terminal: o.terminal === true,
+        completer: complete,
+        prompt: 'annon> ',
+    });
+    const say = (text) => o.output.write(`${text}\n`);
+    const queue = [];
+    /** The catalog listing on screen, by row number; none until `catalog` has run. */
+    let rows;
+    let question;
+    let running;
+    let busy = false;
+    let closed = false;
+    let finish = () => { };
+    const ended = new Promise((resolve) => {
+        finish = resolve;
+    });
+    /** One question at a time. Ctrl-C or a closed input answers nothing, which every caller reads as no. */
+    let asking = Promise.resolve();
+    const ask = (message) => {
+        const answer = asking.then(async () => {
+            question = new AbortController();
+            try {
+                return (await rl.question(message, { signal: question.signal })).trim();
+            }
+            catch {
+                return undefined;
+            }
+            finally {
+                question = undefined;
+            }
+        });
+        asking = answer;
+        return answer;
+    };
+    const adapter = o.adapter({
+        prompt: async (message) => (await ask(message))?.toLowerCase() === 'yes',
+        notify: say,
+    });
+    /** The adapter call of a session line, with a row number of the listing on screen filled in. */
+    const execute = async (input) => {
+        let next = input;
+        // A number means a row of the listing on screen. Without one, or with --shop, the adapter
+        // reads the catalog itself, as for a one-shot `buy <row> --shop <id>`.
+        if (input.command === 'buy' && isRow(input.target) && input.shop === undefined && rows) {
+            const row = rows.get(Number(input.target));
+            if (!row)
+                throw new AdapterError('invalid_arguments', `Row ${input.target} is not in the last catalog listing. Run catalog again.`, 2);
+            say(`Row ${input.target}: ${cleanText(row.title)} (${row.url})`);
+            const { search: _search, ...rest } = input;
+            next = { ...rest, target: row.url };
+        }
+        const owner = running;
+        const result = await adapter(next);
+        // A command dropped with Ctrl-C printed nothing, so it must not change what a row number means.
+        if (!owner?.live)
+            return result;
+        if (input.command === 'catalog' && Array.isArray(result.items))
+            rows = new Map(result.items.map((entry, i) => [rowNumber(input, i), entry]));
+        return result;
+    };
+    async function command(words) {
+        const current = {
+            command: words.find((word) => !word.startsWith('-')) ?? '',
+            waiting: false,
+            live: true,
+            stop: new AbortController(),
+            drop: () => { },
+        };
+        const dropped = new Promise((resolve) => {
+            current.drop = resolve;
+        });
+        running = current;
+        const done = runCli(words, execute, (text) => current.live && say(text), {
+            human: true,
+            notify: (message) => current.live && say(message),
+            signal: current.stop.signal,
+            onWaiting: (waiting) => {
+                current.waiting = waiting;
+            },
+            savePath: async () => (await ask('Save the file now? Path (Enter to skip): ')) || undefined,
+            ...(o.wait ? { wait: o.wait } : {}),
+        });
+        await Promise.race([done, dropped]);
+        running = undefined;
+        // An exit question left open by Ctrl-C is moot once the command is over.
+        question?.abort();
+    }
+    async function line(text) {
+        let words;
+        try {
+            words = splitWords(text);
+        }
+        catch (error) {
+            say(humanError(publicError(error)));
+            return false;
+        }
+        if (words[0] === 'annon')
+            words.shift();
+        if (words.length === 0)
+            return false;
+        if (words.length === 1 && ['exit', 'quit'].includes(words[0]))
+            return true;
+        if (words.length === 1 && words[0] === 'help')
+            say(HELP);
+        else if (words[0] === 'shell')
+            say('This is the session already.');
+        else
+            await command(words);
+        return false;
+    }
+    async function pump() {
+        if (busy)
+            return;
+        busy = true;
+        let leave = false;
+        while (!leave && queue.length > 0)
+            leave = await line(queue.shift());
+        busy = false;
+        if (leave || closed) {
+            rl.close();
+            finish(0);
+        }
+        else
+            rl.prompt();
+    }
+    /** Ctrl-C. Never ends a paying command without a yes, and never touches saved purchase state. */
+    async function interrupt() {
+        if (question) {
+            question.abort();
+            say('');
+            return;
+        }
+        if (!running) {
+            // Drop what was typed; a plain stream has no line to edit.
+            if (o.terminal)
+                rl.write(null, { ctrl: true, name: 'u' });
+            say('\n(type exit to leave)');
+            rl.prompt();
+            return;
+        }
+        const current = running;
+        if (current.waiting) {
+            say('Stopped waiting. The purchase is saved; check it with status.');
+            current.stop.abort();
+        }
+        else if (reading.includes(current.command)) {
+            current.live = false;
+            say('Cancelled.');
+            current.drop();
+        }
+        else {
+            const answer = await ask(paying.includes(current.command)
+                ? 'A payment may be in progress. Exit anyway? (y/N) '
+                : `${current.command} is still running. Exit anyway? (y/N) `);
+            if (running === current && /^y(es)?$/i.test(answer ?? '')) {
+                if (paying.includes(current.command))
+                    say('Leaving. Nothing was removed: check the purchase with annon status before paying again.');
+                rl.close();
+                finish(130);
+            }
+            else if (running === current)
+                say('Still running.');
+        }
+    }
+    rl.on('line', (text) => {
+        queue.push(text);
+        void pump();
+    });
+    rl.on('close', () => {
+        closed = true;
+        void pump();
+    });
+    rl.on('SIGINT', () => void interrupt());
+    return {
+        /** Resolves with the exit code once the person leaves: 0, or 130 after a confirmed Ctrl-C. */
+        run() {
+            say(o.welcome);
+            rl.prompt();
+            return ended;
+        },
+        interrupt,
+    };
+}

package/dist/node/shell/welcome.d.ts

@@ -0,0 +1,9 @@
+import type { Environment } from '../wallets.js';
+/**
+ * A session needs a person at a terminal. Pipes, agent mode and a config that cannot say whether
+ * it is an agent config all keep the one-shot behavior.
+ */
+export declare function sessionAllowed(argv: string[], terminal: boolean, env: Environment): Promise<boolean>;
+/** Human text only for a person at a terminal outside agent mode. */
+export declare const humanOutput: (terminal: boolean, env: Environment) => Promise<boolean>;
+export declare function welcome(env: Environment): Promise<string>;

package/dist/node/shell/welcome.js

@@ -0,0 +1,39 @@
+/** The session's opening lines. Read-only: no prompt, no network, no secret, nothing written. */
+import { join } from 'node:path';
+import { fileStore } from '../../pay/store-node.js';
+import { agentPolicy } from '../agent.js';
+import { loadConfig, trustId } from '../config.js';
+import { cleanText, networkName } from '../output/text.js';
+import { version } from '../version.js';
+const probe = { command: 'shops' };
+/**
+ * A session needs a person at a terminal. Pipes, agent mode and a config that cannot say whether
+ * it is an agent config all keep the one-shot behavior.
+ */
+export async function sessionAllowed(argv, terminal, env) {
+    if (!terminal || !(argv.length === 0 || (argv.length === 1 && argv[0] === 'shell')))
+        return false;
+    try {
+        return !(await agentPolicy(probe, env));
+    }
+    catch {
+        return false;
+    }
+}
+/** Human text only for a person at a terminal outside agent mode. */
+export const humanOutput = async (terminal, env) => terminal &&
+    (await agentPolicy(probe, env).then((agent) => !agent, () => false));
+export async function welcome(env) {
+    const lines = [`Annon ${version}`];
+    try {
+        const c = await loadConfig({ command: 'login' }, env, true);
+        const trusted = c.trustContract === true ||
+            (await fileStore(join(c.stateDir, 'trust')).load(trustId(c))) !== null;
+        lines.push(`Network: ${networkName(c.network)}`, `Account: ${c.signer ? cleanText(c.signer.identity.id) : 'not signed in (run login)'}`, `Contract: ${c.contractId ? `${c.contractId} (${trusted ? 'trusted' : 'not trusted yet'})` : 'not configured'}`);
+    }
+    catch {
+        lines.push('Config: could not be read. Run a command to see why.');
+    }
+    lines.push('Type help for commands, exit to leave. Tab completes.');
+    return lines.join('\n');
+}

package/dist/node/shell/words.d.ts

@@ -0,0 +1 @@
+export declare function splitWords(line: string): string[];

package/dist/node/shell/words.js

@@ -0,0 +1,36 @@
+/** Splits a session line into arguments: spaces separate, quotes and backslashes keep them. */
+import { AdapterError } from '../errors.js';
+export function splitWords(line) {
+    const words = [];
+    let word;
+    let quote;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line.charAt(i);
+        if (quote) {
+            if (ch === quote)
+                quote = undefined;
+            else if (ch === '\\' && quote === '"' && i + 1 < line.length)
+                word += line.charAt(++i);
+            else
+                word += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            word ??= '';
+        }
+        else if (ch === '\\' && i + 1 < line.length)
+            word = (word ?? '') + line.charAt(++i);
+        else if (/\s/.test(ch)) {
+            if (word !== undefined)
+                words.push(word);
+            word = undefined;
+        }
+        else
+            word = (word ?? '') + ch;
+    }
+    if (quote)
+        throw new AdapterError('invalid_arguments', 'A quote is not closed.', 2);
+    if (word !== undefined)
+        words.push(word);
+    return words;
+}

package/dist/node/shops.d.ts

@@ -15,3 +15,8 @@ export declare function selectedShopRules(config: DiscoveryConfig, id: string |
     };
     rules: import("../shops/discovery.js").ShopRules;
 }>;
+/**
+ * `buy <row>`: the resource URL of that row in the listing `catalog` prints for the same `--shop`
+ * and `--search`. The buy then checks the file and its terms as for a URL typed by hand.
+ */
+export declare function catalogRow(input: Input, env: Environment, notify: ((message: string) => void) | undefined, fetcher?: typeof fetch): Promise<Input>;

package/dist/node/shops.js

@@ -4,6 +4,8 @@ import { dirname } from 'node:path';
 import { AnnonError } from '../errors.js';
 import { canonicalManifestUrl, catalog, listShops, readShop, validateDiscoveryConfig, } from '../shops/discovery.js';
 import { configPath } from './agent.js';
+import { AdapterError } from './errors.js';
+import { cleanText } from './output/text.js';
 export const isDiscovery = (input) => ['shops', 'shop', 'catalog'].includes(input.command);
 async function readConfig(path) {
     try {
@@ -72,3 +74,23 @@ export async function selectedShopRules(config, id, fetcher) {
         ? { shop: { manifest: shop.manifest, name: shop.info.name }, rules: shop.info.rules }
         : {};
 }
+/**
+ * `buy <row>`: the resource URL of that row in the listing `catalog` prints for the same `--shop`
+ * and `--search`. The buy then checks the file and its terms as for a URL typed by hand.
+ */
+export async function catalogRow(input, env, notify, fetcher = globalThis.fetch) {
+    const row = Number(input.target);
+    const config = validateDiscoveryConfig(await readConfig(configPath(input, env)));
+    const listing = await catalog(config, {
+        offset: row - 1,
+        limit: 1,
+        ...(input.search !== undefined ? { search: input.search } : {}),
+        ...(input.shop !== undefined ? { shop: input.shop } : {}),
+    }, fetcher);
+    const [entry] = listing.items;
+    if (!entry)
+        throw new AdapterError('invalid_arguments', `The catalog has no row ${row}. Run annon catalog to list the rows.`, 2);
+    notify?.(`Row ${row}: ${cleanText(entry.title)} (${entry.url})`);
+    const { shop: _shop, search: _search, ...rest } = input;
+    return { ...rest, target: entry.url };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defdone/annon",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "Files only the buyer can open: encrypted on the client, the key released by NEAR once the payment is verified.",
   "license": "Apache-2.0",
   "homepage": "https://annon.dev",