@prestack/thread 0.0.1

package/dist/core/thread.d.ts

@@ -0,0 +1,26 @@
+export interface Quote {
+    readonly on: string;
+    readonly said: string;
+}
+export interface Threaded {
+    readonly id: string;
+    readonly at: string;
+    readonly describes: string;
+    readonly version?: number;
+    readonly cites?: readonly Quote[];
+    readonly requires?: readonly string[];
+    readonly takes?: readonly string[];
+    readonly by?: string;
+    readonly runs?: string;
+    readonly declares?: readonly Threaded[];
+    readonly derives?: readonly Threaded[];
+    readonly seeds?: readonly Threaded[];
+}
+export interface Member extends Threaded {
+    readonly version: number;
+}
+export declare const PREFIXES: {
+    readonly workflow: "wf_";
+    readonly view: "vw_";
+    readonly agent: "agt_";
+};

package/dist/core/thread.js

@@ -0,0 +1,5 @@
+export const PREFIXES = {
+    workflow: 'wf_',
+    view: 'vw_',
+    agent: 'agt_',
+};

package/dist/core/tree.d.ts

@@ -0,0 +1,12 @@
+export interface Tree {
+    readonly at: string;
+    readonly dir: string;
+    readonly name: string;
+    readonly root: string;
+}
+export declare class UnthreadedRepositoryError extends Error {
+    constructor(from: string);
+}
+export declare function findTree(from?: string): Tree;
+export declare function strayFiles(root: string, prefix: string, ends: string): readonly string[];
+export declare function inTree(tree: Tree, file: string): string;

package/dist/core/tree.js

@@ -0,0 +1,56 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { cwd } from 'node:process';
+const NAMES = ['_threads', 'threads'];
+const ROOT = 'thread.ts';
+export class UnthreadedRepositoryError extends Error {
+    constructor(from) {
+        super(`no tree above ${from} — looked for a ${NAMES.map((one) => `${one}/`).join(' or ')} directory in every directory up to the filesystem root. ` +
+            'Run `thread init` to write one.');
+        this.name = 'UnthreadedRepositoryError';
+    }
+}
+export function findTree(from = cwd()) {
+    let at = resolve(from);
+    for (;;) {
+        for (const name of NAMES) {
+            const dir = join(at, name);
+            if (existsSync(dir) && statSync(dir).isDirectory())
+                return { at, dir, name, root: join(dir, ROOT) };
+        }
+        const up = dirname(at);
+        if (up === at)
+            throw new UnthreadedRepositoryError(from);
+        at = up;
+    }
+}
+export function strayFiles(root, prefix, ends) {
+    const skip = new Set(['node_modules', '.git', '.next', 'dist', '_generated', 'coverage']);
+    const found = [];
+    const walk = (dir) => {
+        let held;
+        try {
+            held = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const one of held) {
+            if (one.name.startsWith('.') || skip.has(one.name))
+                continue;
+            const path = join(dir, one.name);
+            if (one.isDirectory()) {
+                walk(path);
+                continue;
+            }
+            if (one.name.startsWith(prefix) && one.name.endsWith(ends)) {
+                found.push(relative(root, path).split('\\').join('/'));
+            }
+        }
+    };
+    walk(root);
+    return found.sort();
+}
+export function inTree(tree, file) {
+    return join(tree.dir, file);
+}

package/dist/core/types.d.ts

@@ -0,0 +1,49 @@
+export declare const VALUE_TYPES: readonly ["text", "number", "boolean", "date", "timestamp", "json"];
+export type ValueType = (typeof VALUE_TYPES)[number];
+export declare const KEYBOARDS: readonly ["text", "numeric", "decimal", "tel", "email", "url", "search"];
+export type Keyboard = (typeof KEYBOARDS)[number];
+export declare const ENTRY_MODES: readonly ["plain", "calculator", "masked"];
+export type EntryMode = (typeof ENTRY_MODES)[number];
+export type Checked = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly because: string;
+};
+export declare const held: (value: unknown) => Checked;
+export declare const refused: (because: string) => Checked;
+export interface Facts {
+    readonly locale?: string;
+    readonly currency?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly maxLen?: number;
+    readonly maxBytes?: number;
+    readonly maxDepth?: number;
+    readonly options?: readonly string[];
+    readonly now?: number;
+}
+export interface Format {
+    readonly name: string;
+    readonly type: ValueType;
+    readonly check: (raw: unknown, facts: Facts) => Checked;
+    readonly shown?: (value: unknown, facts: Facts) => string;
+    readonly keyboard?: Keyboard;
+    readonly accepts?: RegExp;
+    readonly maxChars?: number;
+    readonly entry?: EntryMode;
+    readonly mask?: string;
+    readonly secret?: boolean;
+    readonly autocomplete?: string;
+    readonly requires?: readonly string[];
+}
+export declare function stripControl(text: string): string;
+export declare const BOUNDED: Readonly<Partial<Record<ValueType, string>>>;
+export declare const FORMATS: readonly Format[];
+export declare function formatsOf(type: ValueType): readonly Format[];
+export declare function formatNamed(name: string): Format | undefined;
+export declare function plainFormat(type: ValueType): Format;
+export declare function formatFor(type: ValueType, name: string | undefined): Format | undefined;
+export declare function checkValue(type: ValueType, name: string | undefined, raw: unknown, facts?: Facts): Checked;
+export declare function showValue(type: ValueType, name: string | undefined, value: unknown, facts?: Facts): string;

package/dist/core/types.js

@@ -0,0 +1,311 @@
+export const VALUE_TYPES = ['text', 'number', 'boolean', 'date', 'timestamp', 'json'];
+export const KEYBOARDS = ['text', 'numeric', 'decimal', 'tel', 'email', 'url', 'search'];
+export const ENTRY_MODES = ['plain', 'calculator', 'masked'];
+export const held = (value) => ({ ok: true, value });
+export const refused = (because) => ({ ok: false, because });
+export function stripControl(text) {
+    let out = '';
+    for (const character of text) {
+        const point = character.codePointAt(0) ?? 0;
+        const control = point <= 0x08 || point === 0x0b || point === 0x0c || (point >= 0x0e && point <= 0x1f) || (point >= 0x7f && point <= 0x9f);
+        if (!control)
+            out += character;
+    }
+    return out;
+}
+const numeric = (raw) => (typeof raw === 'number' ? raw : Number(raw));
+const SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:']);
+export const BOUNDED = {
+    text: 'number of characters',
+    number: 'value',
+};
+function bounded(one, facts) {
+    if (facts.min !== undefined && one < facts.min)
+        return refused('format.number.below_min');
+    if (facts.max !== undefined && one > facts.max)
+        return refused('format.number.above_max');
+    return held(one);
+}
+function depthWithin(value, limit, depth = 0) {
+    if (depth > limit)
+        return false;
+    if (Array.isArray(value))
+        return value.every((one) => depthWithin(one, limit, depth + 1));
+    if (value !== null && typeof value === 'object')
+        return Object.values(value).every((one) => depthWithin(one, limit, depth + 1));
+    return true;
+}
+const instant = (raw) => typeof raw === 'string' && !Number.isNaN(Date.parse(raw))
+    ? held(new Date(raw).toISOString())
+    : refused('format.timestamp.unreadable');
+const dated = (value, facts, options) => new Intl.DateTimeFormat(facts.locale, options).format(new Date(String(value)));
+export const FORMATS = [
+    {
+        name: 'text',
+        type: 'text',
+        keyboard: 'text',
+        check: (raw, facts) => {
+            if (typeof raw !== 'string')
+                return refused('format.text.not_text');
+            const clean = stripControl(raw).trim();
+            return facts.maxLen !== undefined && clean.length > facts.maxLen ? refused('format.text.too_long') : held(clean);
+        },
+    },
+    {
+        name: 'email',
+        type: 'text',
+        keyboard: 'email',
+        autocomplete: 'email',
+        check: (raw) => {
+            if (typeof raw !== 'string')
+                return refused('format.email.invalid');
+            const one = raw.trim().toLowerCase();
+            return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(one) ? held(one) : refused('format.email.invalid');
+        },
+    },
+    {
+        name: 'tel',
+        type: 'text',
+        keyboard: 'tel',
+        accepts: /[0-9+]/,
+        maxChars: 16,
+        autocomplete: 'tel',
+        check: (raw) => {
+            if (typeof raw !== 'string')
+                return refused('format.tel.invalid');
+            const digits = raw.replace(/[^\d+]/g, '');
+            return /^\+?\d{6,15}$/.test(digits) ? held(digits) : refused('format.tel.invalid');
+        },
+    },
+    {
+        name: 'url',
+        type: 'text',
+        keyboard: 'url',
+        check: (raw) => {
+            if (typeof raw !== 'string')
+                return refused('format.url.invalid');
+            let parsed;
+            try {
+                parsed = new URL(raw.trim());
+            }
+            catch {
+                return refused('format.url.invalid');
+            }
+            return SCHEMES.has(parsed.protocol) ? held(parsed.toString()) : refused('format.url.scheme');
+        },
+    },
+    {
+        name: 'password',
+        type: 'text',
+        secret: true,
+        maxChars: 256,
+        autocomplete: 'current-password',
+        check: (raw) => (typeof raw === 'string' && raw.length >= 8 ? held(raw) : refused('format.password.too_short')),
+    },
+    {
+        name: 'otp',
+        type: 'text',
+        keyboard: 'numeric',
+        accepts: /\d/,
+        maxChars: 6,
+        autocomplete: 'one-time-code',
+        check: (raw) => (typeof raw === 'string' && /^\d{6}$/.test(raw) ? held(raw) : refused('format.otp.invalid')),
+    },
+    {
+        name: 'ref',
+        type: 'text',
+        check: (raw) => (typeof raw === 'string' && /^ref:[a-z0-9/_-]+$/i.test(raw) ? held(raw) : refused('format.ref.invalid')),
+    },
+    {
+        name: 'choice',
+        type: 'text',
+        requires: ['options'],
+        check: (raw, facts) => {
+            if (facts.options === undefined)
+                return refused('format.choice.undeclared_options');
+            return typeof raw === 'string' && facts.options.includes(raw) ? held(raw) : refused('format.choice.undeclared');
+        },
+    },
+    {
+        name: 'number',
+        type: 'number',
+        keyboard: 'decimal',
+        accepts: /[0-9.,-]/,
+        check: (raw, facts) => {
+            const one = numeric(raw);
+            return Number.isFinite(one) ? bounded(one, facts) : refused('format.number.invalid');
+        },
+    },
+    {
+        name: 'integer',
+        type: 'number',
+        keyboard: 'numeric',
+        accepts: /[0-9-]/,
+        check: (raw, facts) => {
+            const one = numeric(raw);
+            return Number.isInteger(one) ? bounded(one, facts) : refused('format.integer.invalid');
+        },
+    },
+    {
+        name: 'money',
+        type: 'number',
+        keyboard: 'decimal',
+        accepts: /[0-9]/,
+        entry: 'calculator',
+        requires: ['currency'],
+        check: (raw, facts) => {
+            const one = numeric(raw);
+            return Number.isFinite(one) ? bounded(one, facts) : refused('format.money.invalid');
+        },
+        shown: (value, facts) => facts.currency === undefined
+            ? String(value)
+            : new Intl.NumberFormat(facts.locale, { style: 'currency', currency: facts.currency }).format(Number(value)),
+    },
+    {
+        name: 'percent',
+        type: 'number',
+        keyboard: 'decimal',
+        accepts: /[0-9.,]/,
+        check: (raw) => {
+            const one = numeric(raw);
+            return Number.isFinite(one) && one >= 0 && one <= 100 ? held(one) : refused('format.percent.range');
+        },
+        shown: (value, facts) => new Intl.NumberFormat(facts.locale, { style: 'percent', maximumFractionDigits: 1 }).format(Number(value) / 100),
+    },
+    {
+        name: 'duration',
+        type: 'number',
+        keyboard: 'numeric',
+        accepts: /[0-9]/,
+        check: (raw) => {
+            const one = numeric(raw);
+            if (!Number.isFinite(one))
+                return refused('format.number.invalid');
+            return one < 0 ? refused('format.duration.negative') : held(one);
+        },
+    },
+    {
+        name: 'rating',
+        type: 'number',
+        keyboard: 'numeric',
+        accepts: /[0-9]/,
+        check: (raw, facts) => {
+            const one = numeric(raw);
+            const ceiling = facts.max ?? 5;
+            return Number.isInteger(one) && one >= 1 && one <= ceiling ? held(one) : refused('format.rating.range');
+        },
+    },
+    {
+        name: 'boolean',
+        type: 'boolean',
+        check: (raw) => {
+            if (typeof raw === 'boolean')
+                return held(raw);
+            if (raw === 'true' || raw === 'false')
+                return held(raw === 'true');
+            return refused('format.boolean.invalid');
+        },
+    },
+    {
+        name: 'date',
+        type: 'date',
+        keyboard: 'numeric',
+        accepts: /[0-9-]/,
+        maxChars: 10,
+        mask: '0000-00-00',
+        entry: 'masked',
+        check: (raw) => {
+            if (typeof raw !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(raw))
+                return refused('format.date.shape');
+            return Number.isNaN(Date.parse(raw)) ? refused('format.date.invalid') : held(raw);
+        },
+        shown: (value, facts) => dated(`${String(value)}T00:00:00Z`, facts, { dateStyle: 'medium', timeZone: 'UTC' }),
+    },
+    {
+        name: 'timestamp',
+        type: 'timestamp',
+        check: instant,
+        shown: (value, facts) => dated(value, facts, { dateStyle: 'medium', timeStyle: 'short' }),
+    },
+    {
+        name: 'elapsed',
+        type: 'timestamp',
+        check: instant,
+        requires: ['now'],
+        shown: (value, facts) => {
+            const now = facts.now ?? Date.parse(new Date().toISOString());
+            const gap = Date.parse(String(value)) - now;
+            const UNITS = [
+                ['year', 31_536_000_000],
+                ['month', 2_592_000_000],
+                ['week', 604_800_000],
+                ['day', 86_400_000],
+                ['hour', 3_600_000],
+                ['minute', 60_000],
+                ['second', 1000],
+            ];
+            const spoken = new Intl.RelativeTimeFormat(facts.locale, { numeric: 'auto' });
+            for (const [unit, span] of UNITS) {
+                if (Math.abs(gap) >= span)
+                    return spoken.format(Math.trunc(gap / span), unit);
+            }
+            return spoken.format(0, 'second');
+        },
+    },
+    {
+        name: 'json',
+        type: 'json',
+        check: (raw, facts) => {
+            if (facts.maxDepth !== undefined && !depthWithin(raw, facts.maxDepth))
+                return refused('format.json.too_deep');
+            const size = JSON.stringify(raw)?.length ?? 0;
+            return facts.maxBytes !== undefined && size > facts.maxBytes ? refused('format.json.too_large') : held(raw);
+        },
+    },
+    {
+        name: 'geo',
+        type: 'json',
+        check: (raw) => {
+            if (raw === null || typeof raw !== 'object')
+                return refused('format.geo.invalid');
+            const { lat, lng } = raw;
+            const within = typeof lat === 'number' && lat >= -90 && lat <= 90 && typeof lng === 'number' && lng >= -180 && lng <= 180;
+            return within ? held({ lat, lng }) : refused('format.geo.invalid');
+        },
+    },
+    {
+        name: 'richtext',
+        type: 'json',
+        check: (raw) => {
+            if (raw === null || typeof raw !== 'object')
+                return refused('format.richtext.invalid');
+            const blocks = raw.blocks;
+            return Array.isArray(blocks) ? held({ blocks }) : refused('format.richtext.invalid');
+        },
+    },
+];
+const BY_NAME = new Map(FORMATS.map((one) => [one.name, one]));
+export function formatsOf(type) {
+    return FORMATS.filter((one) => one.type === type);
+}
+export function formatNamed(name) {
+    return BY_NAME.get(name);
+}
+export function plainFormat(type) {
+    const one = BY_NAME.get(type);
+    if (one === undefined)
+        throw new Error(`no plain format is declared for value type "${type}"`);
+    return one;
+}
+export function formatFor(type, name) {
+    const one = name === undefined ? plainFormat(type) : BY_NAME.get(name);
+    return one === undefined || one.type !== type ? undefined : one;
+}
+export function checkValue(type, name, raw, facts = {}) {
+    const one = formatFor(type, name);
+    return one === undefined ? refused(`format.unusable.${name ?? type}`) : one.check(raw, facts);
+}
+export function showValue(type, name, value, facts = {}) {
+    const one = formatFor(type, name);
+    return one?.shown === undefined ? String(value) : one.shown(value, facts);
+}

package/dist/derivation/attach.d.ts

@@ -0,0 +1,2 @@
+import type { Attaching } from '../core/attach.ts';
+export declare const ATTACH: Attaching;

package/dist/derivation/attach.js

@@ -0,0 +1,61 @@
+import { quoted } from "../core/rows.js";
+const DESCRIBES = 'What turns a declaration into a file: the rows that state something is to be made, and the generators that make it. They are kept apart so you can read what an app declares without opening the machinery that builds it.';
+const DERIVATION_SOURCE = [
+    "import type { Threaded } from '../core/thread.ts'",
+    '',
+    'export const DERIVATION: Threaded = {',
+    "  id: 'derivation',",
+    "  at: '_threads/derivation.ts',",
+    `  describes: ${quoted(DESCRIBES)},`,
+    '  version: 1,',
+    '  derives: [],',
+    '}',
+    '',
+    'export const GENERATORS: readonly Threaded[] = []',
+    '',
+].join('\n');
+const SEEDED = {
+    attaches: [],
+    id: 'derivation',
+    declares: [
+        '    {',
+        '      id: \'derivation\',',
+        '      at: \'_threads/derivation.ts\',',
+        '      describes: \'What turns a declaration into a file: the rows that state something is to be made, and the generators that make it. They are kept apart so you can read what an app declares without opening the machinery that builds it.\',',
+        '      version: 1,',
+        '    },',
+    ].join('\n'),
+};
+const SHIPPED = [
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'build-generator',
+        source: "  {\n    id: 'build-generator',\n    at: 'node_modules/@prestack/thread/dist/derivation/generators/build.js',\n    describes: 'The builder of what this app ships — it reads the row that derives an artifact to learn the entry it comes from, and refuses to resolve any file inside the app the descent never reaches, so a file nothing declares has no way into the thing that runs.',\n    version: 1,\n    by: 'thread build',\n    runs: 'thread build --check',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'release-generator',
+        source: "  {\n    id: 'release-generator',\n    at: 'node_modules/@prestack/thread/dist/derivation/generators/release.js',\n    describes: 'The writer of what a host reads to run this app — it derives the config from what the app already declares, its own build and start commands and the names of every secret it says it must be given, and refuses its own output if a module of this framework ever appears in it, because what a host runs may hold nothing of the scaffolding that assembled it.',\n    version: 1,\n    by: 'thread release',\n    runs: 'thread release --check',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'release-noun',
+        source: "  {\n    id: 'release-noun',\n    at: 'node_modules/@prestack/thread/dist/derivation/makers/release.js',\n    describes: 'The command that declares where this app goes when it leaves your machine. It writes the row saying where this app goes and nothing else, because everything the config needs is already declared somewhere and asking for it again would be the app’s own facts typed a second time.',\n    version: 1,\n    by: 'thread create release',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'generator-noun',
+        source: "  {\n    id: 'generator-noun',\n    at: 'node_modules/@prestack/thread/dist/derivation/generators/derivation.js',\n    describes: 'Declares a generator this app derives a file with. `thread create generator` asks what it is, where its file goes and the command that writes it, then writes the row and seeds the file beside it — so a generator arrives through the same wizard as everything else, and the command it names exists from that moment because the CLI reads every `by:` the tree states.',\n    version: 1,\n    by: 'thread create generator',\n  },",
+    },
+];
+export const ATTACH = {
+    attaches: SEEDED.attaches,
+    id: SEEDED.id,
+    declares: SEEDED.declares,
+    writes: [{ file: 'derivation.ts', source: DERIVATION_SOURCE }],
+    rows: SHIPPED,
+};

package/dist/derivation/generators/build.d.ts

@@ -0,0 +1,16 @@
+import { type Pass } from '../../core/descend.ts';
+declare function wanted(pass: Pass): readonly {
+    entry: string;
+    out: string;
+}[];
+declare function declared(): {
+    readonly name: string;
+    readonly setup: (build: {
+        onLoad: (opts: {
+            filter: RegExp;
+        }, run: (args: {
+            path: string;
+        }) => unknown) => void;
+    }) => void;
+};
+export { declared, wanted };