@prestack/thread 0.0.1

package/dist/integrations/vault.js

@@ -0,0 +1,104 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const VAULT_DIR = '.thread';
+export const SEALED_AT = `${VAULT_DIR}/vault.sealed.json`;
+export const KEY_AT = `${VAULT_DIR}/vault.key`;
+export const ALGORITHM = 'aes-256-gcm';
+export const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const noKey = (root) => new Error(`there is no vault key at ${join(root, KEY_AT)}, so nothing here can open a sealed value. It is deliberately not ` +
+    'in version control — whoever set this app up has it. Ask them for it, or run `thread create secret`, which ' +
+    'generates one when there is none.');
+const unsealable = (named, why) => new Error(`"${named}" is in the sealed store and would not open: ${why}. Either the key is not the one it was sealed under, ` +
+    'or the store has been edited by hand — it is ciphertext, and there is nothing in it to edit.');
+const undeclared = (named, known) => new Error(`nothing may ask for a secret this app does not declare, and "${named}" is not one of ` +
+    `${known.length === 0 ? '(this app declares none)' : known.join(', ')}. A value is asked for by something that ` +
+    'declared it needed it, or not at all.');
+const unset = (named, env) => new Error(`"${named}" is declared and has no value sealed for \`${env}\`. Run \`thread create secret\` and give it one — a ` +
+    'declared secret nothing was ever given is refused here rather than resolved to an empty string.');
+const store = (root) => {
+    const at = join(root, SEALED_AT);
+    if (!existsSync(at))
+        return {};
+    try {
+        const held = JSON.parse(readFileSync(at, 'utf8'));
+        return typeof held === 'object' && held !== null ? held : {};
+    }
+    catch {
+        return {};
+    }
+};
+export const keyOf = (root) => {
+    const at = join(root, KEY_AT);
+    if (!existsSync(at))
+        return undefined;
+    try {
+        const held = Buffer.from(readFileSync(at, 'utf8').trim(), 'base64');
+        return held.length === KEY_BYTES ? held : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export function keyed(root) {
+    const held = keyOf(root);
+    if (held !== undefined)
+        return held;
+    const made = randomBytes(KEY_BYTES);
+    mkdirSync(join(root, VAULT_DIR), { recursive: true });
+    writeFileSync(join(root, KEY_AT), `${made.toString('base64')}\n`, { mode: 0o600 });
+    return made;
+}
+export function seal(root, named, env, value) {
+    const key = keyed(root);
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(ALGORITHM, key, iv);
+    const body = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()]);
+    const held = store(root);
+    held[named] = { ...held[named], [env]: [iv, cipher.getAuthTag(), body].map((one) => one.toString('base64')).join('.') };
+    const sorted = Object.fromEntries(Object.keys(held).sort().map((one) => [one, held[one]]));
+    const at = join(root, SEALED_AT);
+    mkdirSync(dirname(at), { recursive: true });
+    writeFileSync(at, `${JSON.stringify(sorted, null, 2)}\n`);
+}
+export const sealedIn = (root, env) => Object.entries(store(root))
+    .filter(([, held]) => held[env] !== undefined)
+    .map(([named]) => named)
+    .sort();
+function unsealed(key, named, held) {
+    const parts = held.split('.');
+    if (parts.length !== 3)
+        throw unsealable(named, 'it is not three base64 parts separated by dots');
+    const [iv, tag, body] = parts.map((one) => Buffer.from(one, 'base64'));
+    try {
+        const decipher = createDecipheriv(ALGORITHM, key, iv);
+        decipher.setAuthTag(tag);
+        return `${decipher.update(body).toString('utf8')}${decipher.final('utf8')}`;
+    }
+    catch (thrown) {
+        throw unsealable(named, thrown instanceof Error ? thrown.message : String(thrown));
+    }
+}
+export function opened(root, declared, env) {
+    const known = new Set(declared);
+    return async (refs) => {
+        if (refs.length === 0)
+            return {};
+        const key = keyOf(root);
+        if (key === undefined)
+            throw noKey(root);
+        const held = store(root);
+        const out = {};
+        for (const named of refs) {
+            if (!known.has(named))
+                throw undeclared(named, [...known].sort());
+            const sealed = held[named]?.[env];
+            if (sealed === undefined)
+                throw unset(named, env);
+            out[named] = unsealed(key, named, sealed);
+        }
+        return out;
+    };
+}
+export const IGNORES = [KEY_AT];

package/dist/integrity/attach.d.ts

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

package/dist/integrity/attach.js

@@ -0,0 +1,213 @@
+import { named } from "../core/scope.js";
+import { quoted } from "../core/rows.js";
+const DESCRIBES = 'What this app refuses, and the checks that make each refusal actually happen. Every check has one owner, so none of them can be switched off somewhere nobody is looking.';
+const CONSTRAINT = 'The rules the framework enforces on every app that installs it. They are read from the installed package rather than from this tree, so there is nothing here to weaken.';
+const RULES = 'What this app refuses on top of what the framework already does. `thread create rule` asks what to ban, where it applies and what to do instead, then writes the row and the check beside it.';
+const HOME = `node_modules/${named('integrity')}/dist`;
+const GATE = 'Every surface that can refuse, each naming where it lives and the command that runs it, so the gate is derived from what this system declares rather than kept as a string beside it.';
+const COMPILER = 'The compiler run over the files this app declares and no others. A type error is the plainest kind of broken build, so it is refused here rather than found by whoever runs the app next.';
+const INTEGRITY_SOURCE = `import type { Threaded } from '../core/thread.ts'
+
+export const INTEGRITY: Threaded = {
+  id: 'integrity',
+  at: '_threads/integrity.ts',
+  describes: ${quoted(DESCRIBES)},
+  version: 1,
+  declares: [
+    {
+      id: 'compiler',
+      at: 'tsconfig.json',
+      describes: ${quoted(COMPILER)},
+      version: 1,
+      by: 'thread compiler',
+    },
+    {
+      id: 'constraint',
+      at: '${HOME}/constraint.js',
+      describes: ${quoted(CONSTRAINT)},
+      version: 1,
+    },
+    {
+      id: 'rules',
+      at: '_threads/rules.ts',
+      describes: ${quoted(RULES)},
+      version: 1,
+    },
+    {
+      id: 'gate',
+      at: '_threads/gate.ts',
+      describes: ${quoted(GATE)},
+      version: 1,
+    },
+  ],
+}
+`;
+const RULES_SOURCE = `import type { Constraint } from './constraint.ts'
+
+export const RULES: readonly Constraint[] = []
+`;
+const GATE_SOURCE = `import type { Threaded } from '../core/thread.ts'
+
+export const GATE: Threaded = {
+  id: 'gate',
+  at: '_threads/gate.ts',
+  describes: ${quoted(GATE)},
+  version: 1,
+  declares: [],
+}
+`;
+const SEEDED = {
+    attaches: ['@prestack/thread/derivation/attach'],
+    id: 'integrity',
+    declares: [
+        '    {',
+        '      id: \'integrity\',',
+        '      at: \'_threads/integrity.ts\',',
+        '      describes: \'What this app refuses, and the checks that make each refusal actually happen. Every check has one owner, so none of them can be switched off somewhere nobody is looking.\',',
+        '      version: 1,',
+        '    },',
+    ].join('\n'),
+};
+const SHIPPED = [
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'gate-generator',
+        source: "  {\n    id: 'gate-generator',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/gate.js',\n    describes: 'The generator of the gate chain — it reads every row that names a command and refuses one naming none, rather than writing a shorter gate.',\n    version: 1,\n    by: 'thread gate',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'compiler-generator',
+        source: "  {\n    id: 'compiler-generator',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/compiler.js',\n    describes: 'The generator of the compiler config — it walks this tree, leaves out every directory with nothing declared beneath it, and writes that list into the config as what the compiler may not read. It checks the same list before letting the compiler run, because a compile that was pointed at the wrong code is not a compile that passed.',\n    version: 1,\n    by: 'thread compiler',\n    runs: 'thread compiler --check',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'descent-runner',
+        source: "  {\n    id: 'descent-runner',\n    at: 'node_modules/@prestack/thread/dist/integrity/check-threads.js',\n    describes: 'The walk over everything this app tracks, refusing any file no row names. It runs before anything is built, so a file nothing declares stops the build rather than reaching a person.',\n    version: 1,\n    by: 'thread descent',\n    runs: 'thread descent',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'sweep-runner',
+        source: "  {\n    id: 'sweep-runner',\n    at: 'node_modules/@prestack/thread/dist/integrity/sweep.js',\n    describes: 'Every rule — the framework\\'s and this app\\'s own — run over the files it governs. A rule that could not run is named rather than counted as one that passed.',\n    version: 1,\n    by: 'thread sweep',\n    runs: 'thread sweep',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'issues-reader',
+        source: "  {\n    id: 'issues-reader',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/issues.js',\n    describes: 'Everything wrong with this tree in one listing: files no row declares, files that will not compile, and what the rules refuse. It only reports, so it answers even when every other check has stopped.',\n    version: 1,\n    by: 'thread issues',\n    runs: 'thread issues --check',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'publish-runner',
+        source: "  {\n    id: 'publish-runner',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/publish.js',\n    describes: 'Sends this repository\\'s packages to a registry. It derives what each package says about itself first, then builds, then refuses to send anything until the gate, the typecheck, the lint and the seal have each passed, and commits what it derived once the packages are out. The seal is checked rather than regenerated, because a release that rewrites its own seal can never fail it.',\n    version: 1,\n    by: 'thread publish',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'rule-noun',
+        source: "  {\n    id: 'rule-noun',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/rule.js',\n    describes: 'Declares a rule this app holds itself to. `thread create rule` writes the row and seeds the check beside it, so a new rule goes through the same wizard as everything else rather than being written by hand.',\n    version: 1,\n    by: 'thread create rule',\n  },",
+    },
+    {
+        into: 'derivation.ts',
+        list: 'GENERATORS',
+        id: 'seal-generator',
+        source: "  {\n    id: 'seal-generator',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/seal.js',\n    describes: 'Writes the seal: a hash of every built file the integrity package ships, so an installed copy can prove it is the one that went out. With --check it writes nothing and refuses a seal that no longer matches the built files.',\n    version: 1,\n    by: 'thread seal',\n    runs: 'thread seal --check',\n  },",
+    },
+];
+export const ATTACH = {
+    attaches: SEEDED.attaches,
+    id: SEEDED.id,
+    declares: SEEDED.declares,
+    writes: [
+        { file: 'integrity.ts', source: INTEGRITY_SOURCE },
+        { file: 'rules.ts', source: RULES_SOURCE },
+        { file: 'gate.ts', source: GATE_SOURCE },
+    ],
+    retires: [
+        {
+            into: 'gate.ts',
+            list: 'declares',
+            id: 'compiler',
+            why: 'moved into `GENERATORS` beside the generator that writes it, which is what makes `tsconfig.json` settle when declarations move. Left here it would be a second gate step running the same command, which the gate refuses.',
+        },
+        {
+            into: 'gate.ts',
+            list: 'declares',
+            id: 'descent',
+            why: 'its step now comes from the `descent-runner` row this package ships into `GENERATORS`, which states `runs` beside `by`. Left here it would be a second gate step running the same command, which the gate refuses.',
+        },
+        {
+            into: 'gate.ts',
+            list: 'declares',
+            id: 'sweep',
+            why: 'its step now comes from the `sweep-runner` row this package ships into `GENERATORS`, which states `runs` beside `by`. Left here it would be a second gate step running the same command, which the gate refuses.',
+        },
+        {
+            into: 'constraint.ts',
+            list: 'GENERATORS',
+            id: 'sql-duplicate-id',
+            why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+        },
+        {
+            into: 'constraint.ts',
+            list: 'GENERATORS',
+            id: 'sql-name-collision',
+            why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+        },
+        {
+            into: 'constraint.ts',
+            list: 'GENERATORS',
+            id: 'sql-duplicate-parameter',
+            why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+        },
+        {
+            into: 'constraint.ts',
+            list: 'GENERATORS',
+            id: 'sql-unwritable-parameter-type',
+            why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+        },
+        {
+            into: 'constraint.ts',
+            list: 'GENERATORS',
+            id: 'sql-duplicate-returned-column',
+            why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+        },
+        {
+            into: 'constraint.ts',
+            list: 'GENERATORS',
+            id: 'sql-unwritable-return-type',
+            why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+        },
+        {
+            into: 'constraint.ts',
+            list: 'GENERATORS',
+            id: 'sql-unknown-write-target',
+            why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+        },
+        {
+            into: 'constraint.ts',
+            list: 'GENERATORS',
+            id: 'sql-multi-statement',
+            why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+        },
+    ],
+    ignores: ['.thread/', '.next/', 'node_modules/', 'tsconfig.tsbuildinfo'],
+    scripts: {
+        gate: 'thread gate',
+        predev: 'thread gate',
+        dev: 'next dev',
+        prebuild: 'thread gate',
+        build: 'next build',
+        prestart: 'thread gate',
+        start: 'next start',
+    },
+    needs: {
+        '@types/node': '^24.0.0',
+        typescript: '^6.0.0',
+    },
+    rows: SHIPPED,
+};

package/dist/integrity/check-threads.d.ts

@@ -0,0 +1,10 @@
+import { ROOT, THREAD_AT, TREE, descend, type Finding, type Pass } from '../core/descend.ts';
+export { ROOT, THREAD_AT, TREE, descend };
+export type { Finding, Pass };
+export declare function trackedFiles(): readonly string[];
+export declare function unthreaded(pass: Pass, files: readonly string[]): readonly string[];
+export declare function twiceParented(pass: Pass): readonly {
+    readonly at: string;
+    readonly parents: readonly string[];
+}[];
+export declare function refusals(pass: Pass, files: readonly string[]): readonly Finding[];

package/dist/integrity/check-threads.js

@@ -0,0 +1,153 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { argv, stdout } from 'node:process';
+import { exit, invoked } from "../core/invoked.js";
+import { ROOT, THREAD_AT, TREE, configured, descend } from "../core/descend.js";
+import { runChecker } from "../core/finding.js";
+export { ROOT, THREAD_AT, TREE, descend };
+const ELSEWHERE = new Set(['node_modules', '.git']);
+const OWN_IGNORES = (() => {
+    if (spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: ROOT, stdio: 'ignore' }).status === 0) {
+        return undefined;
+    }
+    try {
+        return readFileSync(join(ROOT, '.gitignore'), 'utf8')
+            .split('\n')
+            .map((one) => one.trim())
+            .filter((one) => one !== '' && !one.startsWith('#') && !one.startsWith('!'))
+            .map((one) => one.replace(/^\/+|\/+$/g, ''))
+            .filter((one) => one !== '' && !one.includes('*'));
+    }
+    catch {
+        return [];
+    }
+})();
+function unkept(at) {
+    if (OWN_IGNORES === undefined) {
+        const out = spawnSync('git', ['check-ignore', '-q', '--', at], { cwd: ROOT, stdio: 'ignore' });
+        return out.status === 0;
+    }
+    return OWN_IGNORES.some((one) => at === one || at.startsWith(`${one}/`) || at.split('/').includes(one));
+}
+export function trackedFiles() {
+    const found = [];
+    const walk = (at, under) => {
+        for (const one of readdirSync(at, { withFileTypes: true })) {
+            if (ELSEWHERE.has(one.name))
+                continue;
+            const here = under === '' ? one.name : `${under}/${one.name}`;
+            if (one.isDirectory()) {
+                if (unkept(here))
+                    continue;
+                walk(join(at, one.name), here);
+                continue;
+            }
+            if (unkept(here))
+                continue;
+            found.push(here);
+        }
+    };
+    walk(ROOT, '');
+    return found.sort();
+}
+export function unthreaded(pass, files) {
+    return files.filter((one) => one !== THREAD_AT && !pass.threaded.has(one));
+}
+export function twiceParented(pass) {
+    const found = [];
+    for (const [at, held] of pass.threaded) {
+        const parents = held.filter((one) => one.list === 'declares').map((one) => one.by);
+        if (parents.length > 1)
+            found.push({ at, parents });
+    }
+    return found;
+}
+export function refusals(pass, files) {
+    const found = [...pass.broken, ...pass.findings];
+    const held = configured();
+    if (held.trouble !== undefined) {
+        found.push({
+            file: held.trouble.split(' ')[0] ?? 'tsconfig.json',
+            detail: `the gate fell back to its own compiler options because ${held.trouble}`,
+            instead: 'fix the config, or point the gate at one it can read. Falling back silently means declarations are judged by options nobody chose, and the run says none was found when one was',
+        });
+    }
+    return withFiles(found, pass, files);
+}
+function withFiles(found, pass, files) {
+    for (const one of unthreaded(pass, files)) {
+        const by = pass.mentioned.get(one) ?? [];
+        if (by.length === 0) {
+            found.push({
+                file: one,
+                detail: 'nothing declares this — the descent from the root never reaches it, so it is not wired',
+                instead: 'add a row naming this path to the node that owns it, with all four fields, or delete the file. A file that nothing names is either somebody\'s child nobody wrote down, or it is nobody\'s',
+            });
+            continue;
+        }
+        const cut = by.filter((one) => one !== THREAD_AT && !pass.threaded.has(one));
+        if (cut.length > 0) {
+            found.push({
+                file: one,
+                detail: `broken thread — ${cut.join(' and ')} names this, and nothing declares ${cut.length === 1 ? 'it' : 'them'}, so the descent never arrives`,
+                instead: 'thread the parent. The row is written and the file is where it says, but the line back to the root is cut above it, and nothing below the cut is reached',
+            });
+            continue;
+        }
+        found.push({
+            file: one,
+            detail: `broken thread — ${by.join(' and ')} names this and is itself declared, and the descent still never arrived, so the row was read and never walked`,
+            instead: 'the cut is inside the parent, not above it. Its node answered its own parent with a shape that row does not state, so the descent refused it and stopped there — fix the shape the parent states, and everything under it joins up',
+        });
+    }
+    for (const one of twiceParented(pass)) {
+        found.push({
+            file: one.at,
+            detail: `declared by ${one.parents.join(' and ')} — declares is exactly one parent ever, so its owner, its shape and its origin each have two answers and the tree gives none`,
+            instead: 'keep the row that owns it and delete the other. If both are true, one of them is a `derives` or a `seeds`, which may have many parents because neither of them owns the child',
+        });
+    }
+    return found;
+}
+if (invoked(import.meta.url)) {
+    const pass = await descend();
+    const tracked = trackedFiles();
+    const findings = refusals(pass, tracked);
+    if (argv.includes('--json')) {
+        stdout.write(`${JSON.stringify(findings)}\n`);
+        exit(0);
+    }
+    const fixed = [...pass.threaded.keys()];
+    const reach = new Map();
+    for (const one of fixed)
+        reach.set(dirname(one), (reach.get(dirname(one)) ?? 0) + 1);
+    const held = configured();
+    stdout.write(`threads: descended ${String(pass.declarations)} declaration(s) over ${String(pass.rows)} row(s), naming ${String(fixed.length)} file(s) and coining ${String(pass.coined.size)} word(s).\n`);
+    stdout.write(held.trouble !== undefined
+        ? `threads:   compiler options fallen back to — ${held.trouble}\n`
+        : held.from === ''
+            ? 'threads:   compiler options fallen back to — nothing at the root states a tsconfig, so what the build compiles with may differ from what judged this\n'
+            : `threads:   compiler options taken from ${held.from} at the root — what a package builds with may still differ from this\n`);
+    const here = new Set(tracked);
+    for (const [dir, held] of [...reach].sort()) {
+        const present = tracked.filter((one) => dirname(one) === dir).length;
+        const mine = [...pass.threaded.keys()].filter((one) => dirname(one) === dir && here.has(one)).length;
+        stdout.write(present === 0
+            ? `threads:   ${dir} — ${String(held)} file(s) named, none of them tracked here\n`
+            : `threads:   ${dir} — ${String(mine)} of ${String(present)} tracked file(s) named\n`);
+    }
+    const named = [...pass.threaded.keys()].filter((one) => here.has(one)).length;
+    runChecker('threads', findings, `${String(pass.declarations)} declaration(s), ${String(pass.rows)} row(s), ${String(named)} of ${String(tracked.length)} tracked file(s) named`);
+    const warned = findings.filter((one) => one.severity === 'warning');
+    const refused = findings.filter((one) => one.severity !== 'warning');
+    if (warned.length > 0) {
+        stdout.write(`threads: ${String(warned.length)} of these is a derivation nothing has produced yet — the row states what a ` +
+            'generator would write and no file is there. A generator that refuses to write an empty file is doing its ' +
+            'job, so this is said rather than refused. A derived file that is there and differs from what its generator ' +
+            'writes is the other case, and that one fails.\n');
+    }
+    if (refused.length > 0)
+        exit(1);
+    exit(0);
+}

package/dist/integrity/constraint.d.ts

@@ -0,0 +1,16 @@
+import type { Threaded } from '../core/thread.ts';
+export interface Constraint extends Threaded {
+    readonly version: number;
+    readonly where: {
+        readonly paths: readonly string[];
+        readonly except?: readonly string[];
+    };
+    readonly bans: string;
+    readonly because: string;
+    readonly instead: string;
+    readonly wrong: string;
+    readonly right: string;
+    readonly governs?: string;
+    readonly severity?: 'forbidden' | 'warning';
+}
+export declare const CONSTRAINTS: readonly Constraint[];