@prestack/thread 0.0.3 → 0.1.1

package/dist/knowledge/generators/skills.ts

@@ -1,263 +0,0 @@
-import { spawnSync } from 'node:child_process'
-import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
-import { argv, cwd, env, execPath, stdout } from 'node:process'
-import { fileURLToPath } from 'node:url'
-
-import { SKILLS_AT, declared, nouns, skillOf } from '../../core/asking.ts'
-import { generators } from '../../core/chain.ts'
-import { TREE } from '../../core/descend.ts'
-import { LOADER, exit, invoked } from '../../core/invoked.ts'
-import { ORGANISATION, named } from '../../core/scope.ts'
-import type { Tree } from '../../core/tree.ts'
-import { findTree } from '../../core/tree.ts'
-
-const WHERE = SKILLS_AT
-
-const RECEIPT_LINE = /^[a-z]+: receipt .*$/gm
-
-const NONCE = /--receipt [0-9a-f]{6,}/g
-
-const CRLF = /\r\n/g
-
-const META = fileURLToPath(new URL('../../core/generators/meta.ts', import.meta.url))
-
-const fileFor = (noun: string): string => skillOf(noun)
-
-async function offering(tree: Tree): Promise<ReadonlyMap<string, string>> {
-  const answers = relative(tree.at, META).split('\\').join('/')
-  const found = new Map(nouns(await generators(tree)))
-  found.set('meta', answers)
-  for (const noun of (await declared(tree)).keys()) if (!found.has(noun)) found.set(noun, answers)
-  return found
-}
-
-function printed(root: string, at: string, noun: string): { readonly refused: string; readonly body: string } {
-  if (at === '') return { refused: `nothing in this tree is written by \`thread create ${noun}\``, body: '' }
-
-  const ran = spawnSync(execPath, [...LOADER, join(root, at)], {
-    cwd: root,
-    encoding: 'utf8',
-    env: { ...env, THREAD_NOUN: noun },
-
-    stdio: ['ignore', 'pipe', 'pipe'],
-  })
-  const body = String(ran.stdout ?? '').replace(CRLF, '\n').replace(RECEIPT_LINE, '').trimEnd()
-  const said = String(ran.stderr ?? '').replace(CRLF, '\n').trim().split('\n')[0] ?? ''
-  return { refused: body === '' ? said || 'it printed nothing' : '', body }
-}
-
-function skill(noun: string, body: string): string {
-  return [
-    `# ${noun}`,
-    '',
-    `Everything \`npx thread create ${noun}\` knows, written out by \`npx thread skills\`.`,
-    '',
-    '**Do not edit this file.** It is derived from the tree, so an edit here is reverted the next',
-    'time the command runs, and `npx thread skills --check` fails until it is. If something below is',
-    'wrong or missing, the command that printed it is what to change.',
-    '',
-    `**Read this before you declare a ${noun}.** What follows is what already exists. The reason it`,
-    'exists is that things get built twice by people who did not look — thirteen elements were once',
-    'declared in one app that every one of them already shipped, and the cost was two days of fixes',
-    'landing on a page nobody was looking at. Open what it names before you add to it.',
-    '',
-    'When you are ready to write, run the command yourself for a live receipt. The one printed here',
-    'has been removed on purpose: a receipt is spent by one run and goes stale the moment its sheet',
-    'changes, so a copy kept in a file is always the wrong one.',
-    '',
-    '```',
-    body.replace(NONCE, '--receipt <receipt>'),
-    '```',
-    '',
-  ].join('\n')
-}
-
-const SHEET = `${TREE}_generated/skills.ts`
-
-function sheet(files: readonly string[]): string {
-  const rows = files.map((at) => {
-    const noun = at.slice(WHERE.length + 1, -'.md'.length)
-    return [
-      '    {',
-      `      id: 'skill-${noun}',`,
-      `      at: '${at}',`,
-      `      describes: 'What \`thread create ${noun}\` teaches: the ${noun}s this tree already has, with the sentence each one states, and the rules for declaring another. Written from what that command prints about itself, so the skill and the command cannot disagree.',`,
-      '      version: 1,',
-      "      by: 'thread skills',",
-      "      runs: 'thread skills --check',",
-      '    },',
-    ].join('\n')
-  })
-  return [
-    "import type { Threaded } from '../../thread/core/thread.ts'",
-    '',
-    'export const SKILLS: Threaded = {',
-    "  id: 'skills',",
-    `  at: '${SHEET}',`,
-    "  describes: 'One row per skill `thread skills` writes, so every `skills/<noun>.md` is declared by the command that wrote it instead of being refused as a file nothing named. It sits beside the files it names because the nouns are not known until the tree is read, and a list somebody keeps by hand would go stale the first time a package brings a new maker.',",
-    '  version: 1,',
-    '  derives: [',
-    ...rows,
-    '  ],',
-    '}',
-    '',
-  ].join('\n')
-}
-
-const HERE = (): string => cwd()
-
-const COINS = /by:\s*'thread create ([a-z][a-z0-9-]*)'/g
-
-const ANSWERS_AT = new RegExp(`at:\\s*'node_modules/${ORGANISATION}/[^/]+/(dist/[^']+)'`, 'g')
-
-function ownMakers(root: string): ReadonlyMap<string, string> {
-  const found = new Map<string, string>()
-
-  let names: readonly string[]
-  try {
-    names = readdirSync(join(root, 'src'), { recursive: true }) as readonly string[]
-  } catch {
-    return found
-  }
-
-  for (const one of names) {
-    const path = String(one).split('\\').join('/')
-    if (!path.endsWith('attach.ts')) continue
-
-    let text: string
-    try {
-      text = readFileSync(join(root, 'src', String(one)), 'utf8')
-    } catch {
-      continue
-    }
-
-    for (const row of text.split(/\{\s*$/m)) {
-      const noun = [...row.matchAll(COINS)].at(0)?.[1]
-      const at = [...row.matchAll(ANSWERS_AT)].at(-1)?.[1]
-      if (noun === undefined || at === undefined || found.has(noun)) continue
-      found.set(noun, join(root, at))
-    }
-  }
-
-  return found
-}
-
-function printedOwn(at: string): { readonly refused: string; readonly body: string } {
-  const ran = spawnSync(execPath, ['--experimental-strip-types', at, '--own'], {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  })
-  const body = String(ran.stdout ?? '').replace(CRLF, '\n').replace(RECEIPT_LINE, '').trimEnd()
-  const said = String(ran.stderr ?? '').replace(CRLF, '\n').trim().split('\n')[0] ?? ''
-  return { refused: ran.status === 0 && body !== '' ? '' : said || 'it printed nothing', body }
-}
-
-async function run(): Promise<number> {
-  const own = argv.includes('--own')
-  const checking = argv.includes('--check')
-
-  const root = own ? HERE() : (findTree() as Tree).at
-
-  const mine = own ? ownMakers(root) : new Map<string, string>()
-  const theirs = own ? new Map<string, string>() : await offering(findTree() as Tree)
-  const known = [...(own ? mine : theirs).keys()].sort()
-
-  if (known.length === 0) {
-    stdout.write(
-      own
-        ? 'skills: this package ships no maker, so it coins no noun and has no skill to write.\n'
-        : 'skills: this tree declares no `create` command yet, so there is no method to write down. ' +
-            `Attach a package that brings one — \`npx thread attach ${named('ui')}\` — and run this again.\n`,
-    )
-    return 0
-  }
-
-  const wanted = new Map<string, string>()
-  const skipped: string[] = []
-  for (const noun of known) {
-    const { refused, body } = own ? printedOwn(mine.get(noun) ?? '') : printed(root, theirs.get(noun) ?? '', noun)
-    if (refused !== '') {
-      skipped.push(`  ${noun} — ${refused}`)
-      continue
-    }
-    wanted.set(fileFor(noun), skill(noun, body))
-  }
-
-  if (wanted.size === 0) {
-    stdout.write(
-      `skills: every \`create\` this tree declares refused, so there is no method to write down yet:\n${skipped.join('\n')}\n`,
-    )
-    return 1
-  }
-
-  const made = wanted.size
-  const sheetAt = own ? '' : SHEET
-  if (sheetAt !== '') wanted.set(sheetAt, sheet([...wanted.keys()].sort()))
-
-  const held = new Map<string, string>()
-  try {
-    for (const name of readdirSync(join(root,WHERE))) {
-      if (!name.endsWith('.md')) continue
-      held.set(join(WHERE, name), readFileSync(join(root,WHERE, name), 'utf8').replace(CRLF, '\n'))
-    }
-  } catch {
-
-  }
-
-  if (sheetAt !== '') {
-    try {
-      held.set(sheetAt, readFileSync(join(root, sheetAt), 'utf8').replace(CRLF, '\n'))
-    } catch {
-
-    }
-  }
-
-  const stale = [...held.keys()].filter((one) => !wanted.has(one)).sort()
-  const differs = [...wanted.entries()].filter(([one, text]) => held.get(one) !== text).map(([one]) => one).sort()
-
-  if (checking) {
-    if (stale.length === 0 && differs.length === 0) {
-      stdout.write(
-        `skills: ${String(made)} skill(s), each matching what its own command prints` +
-          (sheetAt === '' ? '' : `, and each declared by a row in ${sheetAt}`) +
-          '.\n',
-      )
-      return 0
-    }
-    for (const one of differs) {
-      stdout.write(
-        `skills: ${one} is not what \`npx thread skills\` writes. A skill is derived from the command ` +
-          'it describes, so an edit here is a second statement of the method and will drift from the ' +
-          'first. Change the command, then run `npx thread skills`.\n',
-      )
-    }
-    for (const one of stale) {
-      stdout.write(
-        `skills: ${one} names a \`create\` this tree no longer declares, so it teaches a command that ` +
-          'will refuse. Run `npx thread skills`.\n',
-      )
-    }
-    return 1
-  }
-
-  for (const [one, text] of wanted) {
-    mkdirSync(dirname(join(root,one)), { recursive: true })
-    writeFileSync(join(root,one), text, 'utf8')
-  }
-  for (const one of stale) rmSync(join(root,one), { force: true })
-
-  stdout.write(
-    `skills: wrote ${String(made)} skill(s) into ${WHERE}/` +
-      (sheetAt === '' ? '' : `, and the ${String(made)} row(s) declaring them into ${sheetAt}`) +
-      (stale.length === 0
-        ? ''
-        : `, and removed ${String(stale.length)} naming a command this tree no longer has`) +
-      '.\n' +
-
-      (skipped.length === 0 ? '' : `skills: no method to keep yet for:\n${skipped.join('\n')}\n`),
-  )
-  return 0
-}
-
-if (invoked(import.meta.url)) exit(await run())

package/dist/operations/generators/grant.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/operations/generators/grant.js

@@ -1,267 +0,0 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-import { spawnSync } from 'node:child_process';
-import { createHash, randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, relative } from 'node:path';
-import { argv, stderr, stdin, stdout } from 'node:process';
-import { createInterface } from 'node:readline';
-import { exit } from "../../core/invoked.js";
-import { ELSEWHERE, wordsIn } from "../../core/asking.js";
-import { generators, settling } from "../../core/chain.js";
-import { holdsRow, listBounds, withRow } from "../../core/rows.js";
-import { findTree, inTree } from "../../core/tree.js";
-import { PUBLIC_ROLE as PUBLIC } from "../../core/actor.js";
-import { ACTOR_FACTS, AGGREGATIONS, COMPARE_OPS, conditioned, said } from "../../core/condition.js";
-import { declaredWords, undeclared } from "../access.js";
-import { descend } from "../../core/descend.js";
-import { operations as woven, types } from "./seed.js";
-const TREE = findTree();
-const FILE = 'access.ts';
-const LIST = 'GRANTS';
-const RECEIPTS = join(tmpdir(), 'thread-grant');
-const RECEIPT = '--receipt';
-const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const here = (path) => relative(TREE.at, path).split('\\').join('/');
-const at = here(inTree(TREE, FILE));
-function refuse(because) {
-    stderr.write(`grant: ${because}\n`);
-    exit(1);
-}
-const kebab = (one) => one.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-import { quoted } from "../../core/rows.js";
-async function taken(file, name) {
-    try {
-        const held = (await import(__rewriteRelativeImportExtension(new URL(`file://${inTree(TREE, file)}`).href)));
-        const list = held[name];
-        return Array.isArray(list) ? list : [];
-    }
-    catch {
-        return [];
-    }
-}
-const entities = await taken('entities.ts', 'ENTITIES');
-const declares = (which) => declaredWords(entities, which, PUBLIC);
-const pass = await descend();
-const operations = [...woven(pass, types(pass))].map(([id]) => ({
-    id,
-    describes: pass.stated.get(id)?.describes ?? '',
-}));
-const grants = await taken(FILE, LIST);
-if (operations.length === 0) {
-    refuse('this app declares no operations, and a grant permits one. Declare what it can be asked to do first — `thread create operation`.');
-}
-const mark = (one) => createHash('sha256').update([one.id, one.on ?? '', one.may.join(','), JSON.stringify(one.to ?? {}), JSON.stringify(one.when ?? {})].join('\n')).digest('hex').slice(0, 6);
-const listing = [
-    entities.length === 0
-        ? 'this app keeps nothing, so a grant here names operations and callers and no entity.'
-        : `${String(entities.length)} entity(s) a grant may be written on:`,
-    ...entities.map((one) => `  ${one.id} — ${[...one.holds.map((each) => each.id), ...(one.links ?? []).map((each) => each.id)].join(', ')}`),
-    '',
-    grants.length === 0
-        ? 'no grants yet, so nothing permits any operation and every caller is refused.'
-        : `${String(grants.length)} grant(s):`,
-    ...grants.map((one) => `  [${mark(one)}] ${one.id} — may ${one.may.join(', ')}${one.on === undefined ? '' : ` on ${one.on}`} — ${one.describes}`),
-].join('\n');
-const words = wordsIn(['new']);
-stdout.write(`${listing}\n`);
-const tree = createHash('sha256').update(TREE.at).digest('hex').slice(0, 16);
-const against = createHash('sha256').update(listing).digest('hex').slice(0, 12);
-const spends = (nonce) => join(RECEIPTS, `${tree}-${nonce}.txt`);
-const OPERANDS = [
-    { word: 'field', means: 'a value or link on the row being judged, by its id' },
-    { word: 'value', means: 'a literal — text, a number, true, false, or null' },
-    { word: 'actor', means: `something about who is asking: ${ACTOR_FACTS.join(', ')}` },
-    { word: 'now', means: 'the moment the row is being touched' },
-    { word: 'ago', means: 'a span before now, written like 30d, 12h, 15m, 45s' },
-    { word: 'agg', means: `a count or total over another entity: ${AGGREGATIONS.join(', ')}` },
-];
-function method(nonce) {
-    return [
-        'what this makes:',
-        '',
-        `  thread grant new <name> ${RECEIPT} ${nonce}`,
-        '',
-        ...ELSEWHERE,
-        '',
-        `${RECEIPT} is spent by one run and refused if ${at} moved after it was issued.`,
-        '',
-        'what `new` asks:',
-        '',
-        '  name:                             kebab-case, and it names the permission rather than the row',
-        '  what does it permit?              one sentence',
-        ...(entities.length === 0
-            ? []
-            : [`  which entity (blank for none):    ${entities.map((one) => one.id).join(', ')}`]),
-        `  which operations (comma separated): ${operations.map((one) => one.id).join(', ')}`,
-        `  which roles:                      ${declares('roles').join(', ')}`,
-        `                                    ${PUBLIC} is everybody — the role an unauthenticated caller`,
-        '                                    already wears. The rest are the options of the value an',
-        '                                    entity names as saying what a caller may do, so a role',
-        '                                    nothing declares is refused here rather than written',
-        `  which entitlements (blank none):  ${declares('entitlements').join(', ') || 'none are declared'}`,
-        '',
-        'then the condition, one step at a time. Nothing is pasted — each answer is offered from what',
-        'the step before it allows, so a condition that cannot be written cannot be typed:',
-        '',
-        '  is:                               pick a side, below',
-        `  op:                               ${COMPARE_OPS.join(', ')}`,
-        '  than:                             pick the other side',
-        '  and / or / done:                  join another comparison, or stop',
-        '',
-        'what a side may be:',
-        '',
-        ...OPERANDS.map((one) => `  ${one.word.padEnd(8)} ${one.means}`),
-        '',
-        'A grant naming no roles, no entitlements and no condition reading the actor is refused when the',
-        'gate is written — it would admit every caller including one nobody authenticated. So one of',
-        'roles, entitlements, or an `actor` condition is required here.',
-    ].join('\n');
-}
-const flagged = argv.indexOf(RECEIPT);
-if (flagged === -1) {
-    const nonce = randomBytes(6).toString('hex');
-    mkdirSync(RECEIPTS, { recursive: true });
-    writeFileSync(spends(nonce), `${against}\n`, 'utf8');
-    stdout.write(`\n${method(nonce)}\n`);
-    stdout.write(`\ngrant: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`);
-    stdout.write(`grant:   thread grant new <name> ${RECEIPT} ${nonce}\n`);
-    exit(0);
-}
-const offered = argv[flagged + 1];
-if (offered === undefined || offered.startsWith('-')) {
-    refuse(`\`${RECEIPT}\` was handed nothing to check. Run \`thread grant\` with no arguments.`);
-}
-let when = '';
-try {
-    when = readFileSync(spends(offered), 'utf8').trim();
-}
-catch {
-    refuse(`\`${offered}\` is not a receipt this tree issued, or it has been spent — one run per receipt.`);
-}
-rmSync(spends(offered), { force: true });
-if (when !== against)
-    refuse(`${at} has changed since that receipt was issued. Run \`thread grant\` again.`);
-const rl = createInterface({ input: stdin, output: stdout });
-const lines = rl[Symbol.asyncIterator]();
-const ask = async (question) => {
-    stdout.write(question);
-    const next = await lines.next();
-    if (next.done === true) {
-        refuse(`the input ended while this was still asking "${question.trim()}". A grant is not written from ` +
-            'half an answer, so nothing was written. Answer every line the listing names, or run it ' +
-            'without a pipe and answer as you go.');
-    }
-    return next.value.trim();
-};
-const withLinks = (one) => ({
-    id: one.id,
-    fields: [...one.holds.map((each) => each.id), ...(one.links ?? []).map((each) => each.id)],
-});
-const holdsOnly = (one) => ({
-    id: one.id,
-    fields: one.holds.map((each) => each.id),
-});
-const say = (line) => {
-    stdout.write(line);
-};
-const name = kebab(words[1] ?? (await ask('name: ')));
-if (name === '' || !KEBAB.test(name)) {
-    rl.close();
-    refuse(`"${name}" cannot be the id of a grant — it is kebab-case, e.g. owner-reads-own-invoice`);
-}
-if (grants.some((one) => one.id === name)) {
-    rl.close();
-    refuse(`\`${name}\` is already granted in ${at}. One id, one policy — two would silently keep whichever was written second.`);
-}
-const describes = await ask('what does it permit? ');
-if (describes === '') {
-    rl.close();
-    refuse(`\`${name}\` was given no meaning, and a row without one is a name nobody can read`);
-}
-const on = entities.length === 0 ? '' : await ask(`which entity (blank if it acts on none) — ${entities.map((one) => one.id).join(', ')}: `);
-const entity = on === '' ? undefined : entities.find((one) => one.id === on);
-if (on !== '' && entity === undefined) {
-    rl.close();
-    refuse(`nothing declares \`${on}\`, and a grant on an entity that does not exist enforces nothing`);
-}
-const may = (await ask(`which operations (comma separated) — ${operations.map((one) => one.id).join(', ')}: `))
-    .split(',')
-    .map((one) => one.trim())
-    .filter((one) => one !== '');
-const stray = may.filter((one) => !operations.some((each) => each.id === one));
-if (may.length === 0 || stray.length > 0) {
-    rl.close();
-    refuse(stray.length > 0
-        ? `this app declares no operation called ${stray.join(', ')} — it declares ${operations.map((one) => one.id).join(', ')}`
-        : 'a grant permits at least one operation, or it permits nothing and may as well not be written');
-}
-const named = (which, answered) => {
-    const wrong = undeclared(answered, declares(which), which);
-    if (wrong !== undefined)
-        refuse(wrong);
-    return answered.split(',').map((one) => one.trim()).filter((one) => one !== '');
-};
-const listed = declares('roles');
-const granted = declares('entitlements');
-const roles = named('roles', await ask(`which roles (comma separated) — ${listed.join(', ')}: `));
-const entitlements = named('entitlements', await ask(`which entitlements (blank for none)${granted.length === 0 ? '' : ` — ${granted.join(', ')}`}: `));
-const condition = entity === undefined
-    ? undefined
-    : await conditioned((_key, question) => ask(question), say, withLinks(entity), entities.map(holdsOnly));
-rl.close();
-const to = roles.length === 0 && entitlements.length === 0
-    ? undefined
-    : { ...(roles.length === 0 ? {} : { roles }), ...(entitlements.length === 0 ? {} : { entitlements }) };
-const row = [
-    '  {',
-    `    id: ${quoted(name)},`,
-    `    at: ${quoted(at)},`,
-    `    describes: ${quoted(describes)},`,
-    '    version: 1,',
-    `    may: [${may.map((one) => quoted(one)).join(', ')}],`,
-    ...(on === '' ? [] : [`    on: ${quoted(on)},`]),
-    ...(to === undefined ? [] : [`    to: ${said(to)},`]),
-    ...(condition === undefined ? [] : [`    when: ${said(condition)},`]),
-    '  },',
-].join('\n');
-const path = inTree(TREE, FILE);
-const text = readFileSync(path, 'utf8');
-const where = listBounds(text, LIST);
-if (where === undefined)
-    refuse(`${at} states no \`${LIST}\` list to grant in`);
-if (holdsRow(text, where, name))
-    refuse(`\`${name}\` is already granted in ${at}`);
-writeFileSync(path, withRow(text, where, row), 'utf8');
-stdout.write(`grant: ${name} may ${may.join(', ')}${on === '' ? '' : ` on ${on}`}, written into ${at}.\n`);
-const settled = settling(TREE.at, await generators(TREE), ['thread grant']);
-for (const one of settled.ran)
-    stdout.write(`${one}\n`);
-const refused = settled.unsettled.filter((one) => one.includes('permits'));
-if (refused.length > 0) {
-    writeFileSync(path, text, 'utf8');
-    stderr.write(`grant: \`${name}\` was taken back out of ${at}, because ${refused.join(', ')} would not settle ` +
-        `after ${String(settled.rounds)} round(s) — the refusal above says what it wanted instead. Nothing else moved.\n`);
-    exit(1);
-}
-if (settled.unsettled.length > 0) {
-    stderr.write(`grant: \`${name}\` is written and stands — the gate generator accepted it. What did not settle is ` +
-        `${settled.unsettled.join(', ')}, which is about the rest of this tree rather than about this row. ` +
-        'Run it yourself and read what it says.\n');
-}
-const records = spawnSync('npx', ['thread'], { cwd: TREE.at, encoding: 'utf8' });
-if (`${records.stdout ?? ''}`.includes('written')) {
-    const kept = spawnSync('npx', ['thread', 'written'], { cwd: TREE.at, encoding: 'utf8' });
-    if (kept.status !== 0) {
-        stdout.write(`${`${kept.stdout ?? ''}${kept.stderr ?? ''}`.trim()}\n`);
-        stderr.write("grant: the row is written and stands; recording it as the method's was refused above.\n");
-    }
-}
-exit(0);