@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/lib/cli-arg.mjs

@@ -1,22 +1,18 @@
 // cli-arg.mjs — the `--name value` and `--flag` readers of the thin CLI entries (the scripts/api call files run as
 // commands, scripts/agent/send.mjs). Pure.
 import { textLine } from './escape.mjs';
-
 /** The value after `--<name>` in argv, else `fallback`. */
 export const arg = (argv, name, fallback = null) => {
-  const i = argv.indexOf(`--${name}`);
-  return i >= 0 ? argv[i + 1] : fallback;
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : fallback;
 };
-
 /** True when argv holds `--<name>`. */
 export const flag = (argv, name) => argv.includes(`--${name}`);
-
 /** The token after the literal `token` in argv, else `fallback` (absent or last). */
 export const valueAfter = (argv, token, fallback = null) => {
-  const i = argv.indexOf(token);
-  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : fallback;
+    const i = argv.indexOf(token);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : fallback;
 };
-
 /**
  * The `--name value` / boolean-flag scan the multi-option CLIs share: `spec` maps each accepted token to a setter
  * `(opts, take)` where `take()` consumes the next token as the value (a missing one reports
@@ -25,86 +21,86 @@ export const valueAfter = (argv, token, fallback = null) => {
  * keeps scanning). Returns `opts`.
  */
 export function parseOpts(argv, spec, fail) {
-  const opts = {};
-  for (let i = 0; i < argv.length; i += 1) {
-    const token = argv[i];
-    const set = spec[token];
-    if (!set) { fail(`unrecognized argument: ${token}`); continue; }
-    const take = () => {
-      i += 1;
-      if (argv[i] === undefined) fail(`${token} needs a value`);
-      return argv[i];
-    };
-    set(opts, take);
-  }
-  return opts;
+    const opts = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        const set = spec[token];
+        if (!set) {
+            fail(`unrecognized argument: ${token}`);
+            continue;
+        }
+        const take = () => {
+            i += 1;
+            if (argv[i] === undefined)
+                fail(`${token} needs a value`);
+            return argv[i];
+        };
+        set(opts, take);
+    }
+    return opts;
 }
-
 /**
  * The `--<name> value` pairs of `names` read from argv: every other token, a missing value and a `--`-led value throw
  * an error suffixed with `usage`.
  */
 export const valueFlags = (argv, names, usage) => {
-  const opts = {};
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (names.includes(arg)) {
-      if (argv[i + 1] === undefined || argv[i + 1].startsWith('--')) throw new Error(`${arg} needs a value; ${usage}`);
-      opts[arg.slice(2)] = argv[++i];
-    } else throw new Error(`unknown argument ${arg}; ${usage}`);
-  }
-  return opts;
+    const opts = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (names.includes(arg)) {
+            if (argv[i + 1] === undefined || argv[i + 1].startsWith('--'))
+                throw new Error(`${arg} needs a value; ${usage}`);
+            opts[arg.slice(2)] = argv[++i];
+        }
+        else
+            throw new Error(`unknown argument ${arg}; ${usage}`);
+    }
+    return opts;
 };
-
 /** A parseOpts `fail` that throws `Error(message)`. */
 export const argThrow = (message) => { throw new Error(message); };
-
 /** Throw `Error('--<name> is required')` for the first of `names` `args` lacks a value for. */
 export const needArgs = (args, names) => {
-  for (const name of names) if (!args[name]) throw new Error(`--${name} is required`);
+    for (const name of names)
+        if (!args[name])
+            throw new Error(`--${name} is required`);
 };
-
 /** Setter entries the `.starciwork`-record CLIs share: `--work <dir> --record <id> --cwd <dir>`. */
 export const workRecordSpec = {
-  '--work': (o, take) => { o.work = take(); },
-  '--record': (o, take) => { o.record = take(); },
-  '--cwd': (o, take) => { o.cwd = take(); },
+    '--work': (o, take) => { o.work = take(); },
+    '--record': (o, take) => { o.record = take(); },
+    '--cwd': (o, take) => { o.cwd = take(); },
 };
-
 /** `--work --record --cwd` for the example-record CLIs; throws on an unknown token or a missing value. */
 export function parseExampleArgs(argv) {
-  const args = parseOpts(argv, workRecordSpec, argThrow);
-  needArgs(args, ['work', 'record', 'cwd']);
-  return args;
+    const args = parseOpts(argv, workRecordSpec, argThrow);
+    needArgs(args, ['work', 'record', 'cwd']);
+    return args;
 }
-
 /** Setter entries the record-scoped op CLIs share: `--op`, `--records` (csv, accumulated), `--state`, `--json`, `--help`/`-h` (calls `help`). */
 const opRecordSpec = (help) => ({
-  '--op': (o, take) => { o.op = take(); },
-  '--records': (o, take) => { o.records = [...(o.records ?? []), ...take().split(',')]; },
-  '--state': (o, take) => { o.state = take(); },
-  '--json': (o) => { o.json = true; },
-  '--help': () => help(), '-h': () => help(),
+    '--op': (o, take) => { o.op = take(); },
+    '--records': (o, take) => { o.records = [...(o.records ?? []), ...take().split(',')]; },
+    '--state': (o, take) => { o.state = take(); },
+    '--json': (o) => { o.json = true; },
+    '--help': () => help(), '-h': () => help(),
 });
-
 /** The final value of an accumulated `--records` list: trimmed, blanks dropped, deduplicated. */
 const recordsList = (args) => [...new Set((args.records ?? []).map((s) => s.trim()).filter(Boolean))];
-
 /**
  * The `usage` + `parseArgs` pair the record-scoped op CLIs share: `usage` prints `usageText` to stderr and exits
  * with the code; `parseArgs` scans the opRecordSpec options plus the CLI's own `spec` setters and resolves
  * `records` to its deduplicated list (recordsList).
  */
 export function opCli(usageText, spec) {
-  const usage = (code) => { console.error(usageText); process.exit(code); };
-  const parseArgs = (argv) => {
-    const a = parseOpts(argv, { ...opRecordSpec(() => usage(0)), ...spec }, () => usage(2));
-    a.records = recordsList(a);
-    return a;
-  };
-  return { usage, parseArgs };
+    const usage = (code) => { console.error(usageText); return process.exit(code); };
+    const parseArgs = (argv) => {
+        const a = parseOpts(argv, { ...opRecordSpec(() => usage(0)), ...spec }, () => usage(2));
+        a.records = recordsList(a);
+        return a;
+    };
+    return { usage, parseArgs };
 }
-
 /**
  * The prelude the multi-verb lesson CLIs share (scripts/machine/lessons.mjs, scripts/supervisor/lesson-actions.mjs):
  * `verb` is argv[0]; `value(n)` the token after `--n` (null when absent); `csv(v)` a trimmed non-empty list;
@@ -112,9 +108,9 @@ export function opCli(usageText, spec) {
  * holds one element per line; control characters inside a line (CR, LF, escape sequences) print as \uXXXX.
  */
 export function verbCli(argv = process.argv.slice(2)) {
-  const value = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] ?? null : null; };
-  const csv = (v) => String(v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
-  const asJson = argv.includes('--json');
-  const print = (r, human) => console.log(asJson ? JSON.stringify(r) : [human].flat().map((line) => textLine(line)).join('\n'));
-  return { argv, verb: argv[0], value, csv, asJson, print };
+    const value = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] ?? null : null; };
+    const csv = (v) => String(v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    const asJson = argv.includes('--json');
+    const print = (r, human) => console.log(asJson ? JSON.stringify(r) : [human].flat().map((line) => textLine(line)).join('\n'));
+    return { argv, verb: argv[0], value, csv, asJson, print };
 }

package/runtime/scripts/lib/command-tokens.d.mts

@@ -0,0 +1,11 @@
+/** One token of a command tail: its text and whether it sits in optional text. */
+export interface CommandToken {
+    text: string;
+    optional: boolean;
+}
+/** A value written as a placeholder: <id>, $VAR, ${VAR}, {x}. */
+export declare const isPlaceholder: (t: string) => boolean;
+/** <a|b>: alternatives written inside angle brackets. */
+export declare const isAlternation: (t: string) => boolean;
+/** The flat tokens {text, optional} of a command tail. */
+export declare function tokenise(text: string, optional?: boolean): CommandToken[];

package/runtime/scripts/lib/command-tokens.mjs

@@ -3,9 +3,7 @@
 // A tail is split into shell-like atoms: a run of non-space characters in which <...>, [...], {...}, (...) and quoted parts may hold
 // spaces. [..] and (..) groups are optional text (all their alternatives are named); a (..) group that opens with a plain word is
 // commentary and ends the command; a token that ends a sentence ends the command.
-
 import { trimEndWhile } from './trim-end.mjs';
-
 const CLOSERS = { '<': '>', '[': ']', '{': '}', '(': ')' };
 const TRAILING_CHARS = '.,;:!?)\'"`]}';
 const GROUP_TRAILING_CHARS = '.,;:)';
@@ -13,114 +11,115 @@ const CUT = { text: '#', optional: false };
 const OPENS_VALUE = /^\s*(--|<|\[|\$)/;
 const QUOTED = /^(['"]).*\1$/;
 const NAME = /^[\w.]+$/;
-
 /** The index of the character that closes the bracket group opened at `from`, or -1 when it never closes. */
 function groupEnd(s, from) {
-  const open = s[from];
-  let depth = 0;
-  for (let j = from; j < s.length; j += 1) {
-    if (s[j] === open) depth += 1;
-    else if (s[j] === CLOSERS[open]) {
-      depth -= 1;
-      if (depth === 0) return j;
+    const open = s.charAt(from);
+    let depth = 0;
+    for (let j = from; j < s.length; j += 1) {
+        if (s[j] === open)
+            depth += 1;
+        else if (s[j] === CLOSERS[open]) {
+            depth -= 1;
+            if (depth === 0)
+                return j;
+        }
     }
-  }
-  return -1;
+    return -1;
 }
-
 /** The end of the atom that starts at `start`. */
 function readAtom(s, start) {
-  let i = start;
-  while (i < s.length && !/\s/.test(s[i])) {
-    const c = s[i];
-    if (c in CLOSERS) {
-      const end = groupEnd(s, i);
-      if (end < 0) return s.length;
-      i = end + 1;
-    } else if ((c === '"' || c === "'") && (i === start || s[i - 1] === '=')) {
-      const j = s.indexOf(c, i + 1);
-      i = j < 0 ? i + 1 : j + 1;
-    } else i += 1;
-  }
-  return i;
+    let i = start;
+    while (i < s.length && !/\s/.test(s.charAt(i))) {
+        const c = s.charAt(i);
+        if (c in CLOSERS) {
+            const end = groupEnd(s, i);
+            if (end < 0)
+                return s.length;
+            i = end + 1;
+        }
+        else if ((c === '"' || c === "'") && (i === start || s[i - 1] === '=')) {
+            const j = s.indexOf(c, i + 1);
+            i = j < 0 ? i + 1 : j + 1;
+        }
+        else
+            i += 1;
+    }
+    return i;
 }
-
 const stripTrailing = (atom, chars) => trimEndWhile(atom, (c) => chars.includes(c));
-
 /** The maximal run of sentence punctuation at the end of an atom: {index, text}, or null. */
 const trailingRun = (atom) => {
-  let start = atom.length;
-  while (start > 0 && TRAILING_CHARS.includes(atom[start - 1])) start -= 1;
-  return start < atom.length ? { index: start, text: atom.slice(start) } : null;
+    let start = atom.length;
+    while (start > 0 && TRAILING_CHARS.includes(atom.charAt(start - 1)))
+        start -= 1;
+    return start < atom.length ? { index: start, text: atom.slice(start) } : null;
 };
-
 // ${NAME}, $NAME and ${NAME with an optional closing brace
 const isDollarName = (t) => {
-  if (!t.startsWith('$')) return false;
-  let rest = t.slice(1);
-  if (rest.startsWith('{')) rest = rest.slice(1);
-  if (rest.endsWith('}')) rest = rest.slice(0, -1);
-  return NAME.test(rest);
+    if (!t.startsWith('$'))
+        return false;
+    let rest = t.slice(1);
+    if (rest.startsWith('{'))
+        rest = rest.slice(1);
+    if (rest.endsWith('}'))
+        rest = rest.slice(0, -1);
+    return NAME.test(rest);
 };
-
 // an <...> part with at least one character inside
 const hasAnglePart = (t) => {
-  for (let i = t.indexOf('<'); i >= 0; i = t.indexOf('<', i + 1)) {
-    if (t.indexOf('>', i + 1) > i + 1) return true;
-  }
-  return false;
+    for (let i = t.indexOf('<'); i >= 0; i = t.indexOf('<', i + 1)) {
+        if (t.indexOf('>', i + 1) > i + 1)
+            return true;
+    }
+    return false;
 };
-
 const wrapped = (t, open, close) => t.startsWith(open) && t.endsWith(close) && t.length >= open.length + close.length;
-
 /** A value written as a placeholder: <id>, $VAR, ${VAR}, {x}. */
 export const isPlaceholder = (t) => wrapped(t, '<', '>') || isDollarName(t) || wrapped(t, '${', '}') || wrapped(t, '{', '}')
-  || hasAnglePart(t) || t.includes('${');
-
+    || hasAnglePart(t) || t.includes('${');
 /** <a|b>: alternatives written inside angle brackets. */
 export const isAlternation = (t) => {
-  if (!wrapped(t, '<', '>')) return false;
-  const bar = t.indexOf('|', 2);
-  return bar > 0 && bar <= t.length - 3;
+    if (!wrapped(t, '<', '>'))
+        return false;
+    const bar = t.indexOf('|', 2);
+    return bar > 0 && bar <= t.length - 3;
 };
-
 const isGroup = (closed) => closed.length > 2 && ((closed.startsWith('[') && closed.endsWith(']')) || (closed.startsWith('(') && closed.endsWith(')')));
 const unquote = (atom) => (atom.length > 1 && QUOTED.test(atom) ? atom.slice(1, -1) : atom);
-
 // {tokens, stop} of a bracket group atom
 function groupTokens(atom, closed) {
-  const body = closed.slice(1, -1);
-  if (atom.startsWith('(') && !OPENS_VALUE.test(body)) return { tokens: [CUT], stop: true };
-  return {
-    tokens: tokenise(body, true).filter((t) => t.text !== '|'),
-    stop: closed !== atom && /[.,;:]/.test(atom.slice(closed.length)),
-  };
+    const body = closed.slice(1, -1);
+    if (atom.startsWith('(') && !OPENS_VALUE.test(body))
+        return { tokens: [CUT], stop: true };
+    return {
+        tokens: tokenise(body, true).filter((t) => t.text !== '|'),
+        stop: closed !== atom && /[.,;:]/.test(atom.slice(closed.length)),
+    };
 }
-
 // {tokens, stop} of a plain atom
 function plainTokens(atom, optional) {
-  const tail = /^\.{1,3}$/.test(atom) ? null : trailingRun(atom);
-  const trimmed = tail !== null && !isPlaceholder(atom);
-  const bare = trimmed ? atom.slice(0, tail.index) : atom;
-  return { tokens: bare ? [{ text: bare, optional }] : [], stop: trimmed && /[^\]]/.test(tail.text) };
+    const tail = /^\.{1,3}$/.test(atom) ? null : trailingRun(atom);
+    const trimmed = tail !== null && !isPlaceholder(atom);
+    const bare = trimmed ? atom.slice(0, tail.index) : atom;
+    return { tokens: bare ? [{ text: bare, optional }] : [], stop: trimmed && /[^\]]/.test(tail.text) };
 }
-
 /** The flat tokens {text, optional} of a command tail. */
 export function tokenise(text, optional = false) {
-  const tokens = [];
-  let i = 0;
-  while (i < text.length) {
-    if (/\s/.test(text[i])) {
-      i += 1;
-      continue;
+    const tokens = [];
+    let i = 0;
+    while (i < text.length) {
+        if (/\s/.test(text.charAt(i))) {
+            i += 1;
+            continue;
+        }
+        const end = readAtom(text, i);
+        const atom = text.slice(i, end);
+        i = end;
+        const closed = atom.startsWith('[') ? stripTrailing(atom, GROUP_TRAILING_CHARS) : atom;
+        const step = isGroup(closed) ? groupTokens(atom, closed) : plainTokens(unquote(atom), optional);
+        tokens.push(...step.tokens);
+        if (step.stop)
+            break;
     }
-    const end = readAtom(text, i);
-    const atom = text.slice(i, end);
-    i = end;
-    const closed = atom.startsWith('[') ? stripTrailing(atom, GROUP_TRAILING_CHARS) : atom;
-    const step = isGroup(closed) ? groupTokens(atom, closed) : plainTokens(unquote(atom), optional);
-    tokens.push(...step.tokens);
-    if (step.stop) break;
-  }
-  return tokens;
+    return tokens;
 }

package/runtime/scripts/lib/compose-values.d.mts

@@ -0,0 +1,6 @@
+/** Compose mapping/list entries; callers choose how bare keys and non-string list items are interpreted. */
+export declare function composeEntries(value: unknown, { missingValue, stringsOnly, isMapping }?: {
+    missingValue?: unknown;
+    stringsOnly?: boolean;
+    isMapping?: (value: unknown) => boolean;
+}): [string, unknown][];

package/runtime/scripts/lib/compose-values.mjs

@@ -1,11 +1,11 @@
 import { isPlainObject } from '../../engine/plain-object.mjs';
-
 /** Compose mapping/list entries; callers choose how bare keys and non-string list items are interpreted. */
 export function composeEntries(value, { missingValue = '', stringsOnly = false, isMapping = isPlainObject } = {}) {
-  if (!Array.isArray(value)) return Object.entries(isMapping(value) ? value : {});
-  const entries = stringsOnly ? value.filter(entry => typeof entry === 'string') : value;
-  return entries.map(entry => {
-    const text = String(entry), separator = text.indexOf('=');
-    return separator < 0 ? [text, missingValue] : [text.slice(0, separator), text.slice(separator + 1)];
-  });
+    if (!Array.isArray(value))
+        return Object.entries(isMapping(value) ? value : {});
+    const entries = stringsOnly ? value.filter(entry => typeof entry === 'string') : value;
+    return entries.map((entry) => {
+        const text = String(entry), separator = text.indexOf('=');
+        return separator < 0 ? [text, missingValue] : [text.slice(0, separator), text.slice(separator + 1)];
+    });
 }

package/runtime/scripts/lib/css-rules.d.mts

@@ -0,0 +1,36 @@
+/** One style rule of a stylesheet: resolved selectors, the at-rule preludes it sits in, its `@apply` utilities and its declarations. */
+export interface CssRule {
+    selectors: string[];
+    wraps: string[];
+    apply: string[];
+    declarations: {
+        property: string;
+        value: string;
+    }[];
+}
+/** The text without `/* ... *\/` comments. */
+export declare const stripCssComments: (text: unknown) => string;
+/** Split `text` at top-level `separator` characters (outside parentheses, brackets and quotes). */
+export declare function splitTopLevel(text: string, separator: string): string[];
+/**
+ * Every style rule of `text`: `{selectors, wraps, apply, declarations}`. `selectors` are fully resolved, `wraps` the at-rule preludes
+ * (`@media (forced-colors: active)`, `@layer x`) the rule sits in, `apply` the `@apply` utilities and `declarations` the plain properties.
+ */
+export declare function cssRules(text: unknown): CssRule[];
+/** The subject compound of a selector: the part after the last combinator, outside brackets and parentheses. */
+export declare function subjectCompound(selector: string): string;
+/** The `.class` names a selector mentions, outside attribute brackets. */
+export declare function selectorClasses(selector: string): string[];
+/** The `[data-...]` attribute names a selector mentions. */
+export declare function selectorAttributes(selector: string): {
+    name: string;
+    value: string | null;
+}[];
+/** The paint family a CSS property belongs to (`padding-inline` is `padding`), or the property itself. */
+export declare function propertyFamily(property: unknown): string | null;
+/** The paint families one `@apply` utility sets (`ps-7` is `padding`, `text-muted` is `color`); an unrecognised utility sets none. */
+export declare function utilityFamilies(utility: unknown): string[];
+/** The paint families a rule sets, from its `@apply` utilities and its declarations. */
+export declare function ruleFamilies(rule: Pick<CssRule, 'apply' | 'declarations'>): string[];
+/** The paint families a strict Grammar may only change through a declared vendor override. */
+export declare function repaintFamilies(rule: Pick<CssRule, 'apply' | 'declarations'>): string[];