trunative 1.0.0

package/dist/commands/install.js

@@ -0,0 +1,76 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { STACKS } from '../compile.js';
+import { readSources, resolve, write } from '../emit.js';
+import { writeLock } from '../lock.js';
+import { AGENT_ROOTS, DEFAULT_AGENT_ROOT, agentFor, briefCandidates, packagedSkillDir, variantName, } from '../paths.js';
+import { hashFiles, hashSkill, readSkillName } from '../skill.js';
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Agent directories already present in the project. A project with no agent
+ * directory gets .claude, which is the common default.
+ */
+async function detectAgentRoots(cwd) {
+    const found = [];
+    for (const root of AGENT_ROOTS) {
+        if (await exists(join(cwd, root))) {
+            found.push(root);
+        }
+    }
+    return found.length > 0 ? found : [DEFAULT_AGENT_ROOT];
+}
+/**
+ * The stack the project recorded, from the "Stack:" line init writes at the top
+ * of STACK.md. Absent means the generic copy, which carries every branch.
+ */
+export async function readStack(cwd) {
+    for (const candidate of briefCandidates(cwd, 'STACK.md')) {
+        let source;
+        try {
+            source = await readFile(candidate, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const match = /^Stack:\s*([a-z-]+)\s*$/m.exec(source);
+        const stack = match?.[1];
+        return stack && STACKS.includes(stack) ? stack : undefined;
+    }
+    return undefined;
+}
+export async function install(options) {
+    const { cwd, version } = options;
+    const name = await readSkillName(packagedSkillDir);
+    const sources = await readSources();
+    const stack = options.stack ?? (await readStack(cwd));
+    const skill = variantName(name, stack);
+    const roots = options.dirs ?? (await detectAgentRoots(cwd));
+    const targets = [];
+    for (const root of roots) {
+        const agent = options.dirs ? 'other' : agentFor(root);
+        const target = stack ? { agent, stack } : { agent };
+        const files = resolve(sources, target);
+        const dir = options.dirs ? root : [root, 'skills', skill].join('/');
+        await write(files, join(cwd, ...dir.split('/')));
+        targets.push({ dir, agent, ...(stack ? { stack } : {}), hash: hashFiles(files) });
+        console.log(`installed ${skill} into ${dir} (resolved for ${agent})`);
+    }
+    await writeLock(cwd, {
+        version,
+        skill,
+        hash: await hashSkill(packagedSkillDir),
+        installedAt: new Date().toISOString(),
+        targets,
+    });
+    console.log(`wrote .trunative/skill.lock (${stack ? `stack ${stack}` : 'no stack recorded yet'})`);
+    console.log('run "npx trunative doctor" to check the project briefs');
+    return 0;
+}

package/dist/commands/lint.js

@@ -0,0 +1,87 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readGraph } from '../graph.js';
+import { packageRoot, packagedSkillDir } from '../paths.js';
+/** Written prose the skill never ships, checked here rather than by eye. */
+const FORBIDDEN = [
+    { pattern: /[—–]/, kind: 'dash', detail: 'em dash or en dash' },
+    { pattern: /<if:|<endif>|<else>/, kind: 'old syntax', detail: 'pre-MDX conditional' },
+];
+async function prose(skillDir, files) {
+    const findings = [];
+    for (const file of files) {
+        let source;
+        try {
+            source = await readFile(join(skillDir, file), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        source.split(/\r?\n/).forEach((line, index) => {
+            for (const rule of FORBIDDEN) {
+                if (rule.pattern.test(line)) {
+                    findings.push({ kind: rule.kind, detail: rule.detail, file, line: index + 1 });
+                }
+            }
+        });
+    }
+    return findings;
+}
+/**
+ * The README summarises the rules and cites them by id, so a rename that misses
+ * it leaves the entry point of the repository pointing at nothing.
+ */
+async function readmeCitations(graph) {
+    const findings = [];
+    let source;
+    try {
+        source = await readFile(join(packageRoot, 'README.md'), 'utf8');
+    }
+    catch {
+        return findings;
+    }
+    const ids = new Set(graph.rules.map((rule) => rule.id));
+    const prefixes = [...new Set(graph.rules.map((rule) => rule.id.split('-')[0] + '-'))];
+    source.split(/\r?\n/).forEach((line, index) => {
+        for (const match of line.matchAll(/`([a-z0-9][a-z0-9-]*)`/g)) {
+            const token = match[1];
+            if (ids.has(token) || prefixes.includes(token) || !prefixes.some((p) => token.startsWith(p))) {
+                continue;
+            }
+            findings.push({
+                kind: 'dangling id',
+                detail: `\`${token}\` is defined nowhere`,
+                file: 'README.md',
+                line: index + 1,
+            });
+        }
+    });
+    return findings;
+}
+export async function lint(options) {
+    const graph = await readGraph(packagedSkillDir);
+    const markdown = [
+        'SKILL.md',
+        ...graph.files.flow,
+        ...graph.files.heuristics,
+        ...graph.files.references,
+    ].filter((file) => file.endsWith('.md'));
+    const findings = [
+        ...graph.findings,
+        ...(await prose(packagedSkillDir, markdown)),
+        ...(await prose(packageRoot, ['README.md'])),
+        ...(await readmeCitations(graph)),
+    ];
+    if (findings.length === 0) {
+        console.log(`PASS  ${graph.rules.length} rules, ${graph.mentions.length} citations, 0 findings`);
+        console.log(`      run against ${options.cwd === packageRoot ? 'this repository' : packagedSkillDir}`);
+        return 0;
+    }
+    const width = Math.max(...findings.map((finding) => finding.kind.length));
+    for (const finding of findings) {
+        const where = finding.file ? `${finding.file}${finding.line ? `:${finding.line}` : ''}  ` : '';
+        console.log(`FAIL  ${finding.kind.padEnd(width)}  ${where}${finding.detail}`);
+    }
+    console.log(`\n${findings.length} finding(s) in the written skill.`);
+    return 1;
+}

package/dist/commands/rubric.js

@@ -0,0 +1,104 @@
+import { DETECTORS } from '../detect/rules.js';
+import { packagedSkillDir } from '../paths.js';
+import { readAlwaysInScope, readHeuristics, readIndexFiles, } from '../heuristics.js';
+const FORMATS = ['markdown', 'json', 'ids'];
+function matches(rule, only) {
+    return only.some((term) => term === rule.file || rule.id === term || rule.id.startsWith(term));
+}
+/**
+ * Base files are in every rubric. Beyond them, whole files when they match,
+ * and single rules when the term is an id.
+ */
+function scope(heuristics, base, only) {
+    if (only.length === 0) {
+        return heuristics;
+    }
+    return heuristics
+        .map((heuristic) => ({
+        ...heuristic,
+        rules: base.includes(heuristic.file)
+            ? heuristic.rules
+            : heuristic.rules.filter((rule) => matches(rule, only)),
+    }))
+        .filter((heuristic) => heuristic.rules.length > 0);
+}
+function row(rule, source) {
+    const flags = [
+        rule.always ? 'always' : '',
+        rule.evidence === 'device' ? 'device' : '',
+        source ? `from ${source}` : '',
+    ]
+        .filter(Boolean)
+        .join(', ');
+    const head = `- \`${rule.id}\` (score: _, evidence: _)${flags ? ` [${flags}]` : ''}`;
+    const criterion = rule.check || `no Check line in the file, judge it against "${rule.title}"`;
+    return `${head}\n  ${criterion}`;
+}
+function markdown(all, scoped, base, version) {
+    const total = all.reduce((count, heuristic) => count + heuristic.rules.length, 0);
+    const inScope = scoped.reduce((count, heuristic) => count + heuristic.rules.length, 0);
+    const emitted = new Set(scoped.flatMap((heuristic) => heuristic.rules.map((rule) => rule.id)));
+    const missing = all
+        .flatMap((heuristic) => heuristic.rules.map((rule) => [heuristic, rule]))
+        .filter(([, rule]) => rule.always && !emitted.has(rule.id));
+    const extras = scoped
+        .map((heuristic) => heuristic.file)
+        .filter((file) => !base.includes(file));
+    const out = [
+        '# Review checklist',
+        '',
+        `Generated by trunative ${version}. ${inScope + missing.length} rules in scope, of ${total}.`,
+        `Base: ${base.join(', ')}. Extra: ${extras.length > 0 ? extras.join(', ') : 'none'}.`,
+        '',
+        'Score each rule 1 to 5, or mark it n/a with a reason, or unrun. A row marked',
+        '[device] may not be graded from the source alone. The anchors, the evidence',
+        'values and what happens to the denominator are in `flow/review.md`.',
+    ];
+    if (missing.length > 0) {
+        out.push('', '## Always in scope', '', 'Scored on every run, whatever the screen is. Not available as n/a.', '', ...missing.map(([heuristic, rule]) => row(rule, heuristic.path)));
+    }
+    for (const heuristic of scoped) {
+        out.push('', `## ${heuristic.file}, ${heuristic.path}`, '', ...heuristic.rules.map((rule) => row(rule)));
+        if (heuristic.device) {
+            out.push('', `Not from a diff: ${heuristic.device}`);
+        }
+    }
+    return `${out.join('\n')}\n`;
+}
+export async function rubric(options) {
+    const format = options.format ?? 'markdown';
+    if (!FORMATS.includes(format)) {
+        console.error(`unknown --format "${format}", expected ${FORMATS.join(', ')}`);
+        return 1;
+    }
+    const only = options.only ?? [];
+    const all = await readHeuristics(packagedSkillDir);
+    const base = await readIndexFiles(packagedSkillDir, 'base');
+    const scoped = scope(all, base, only);
+    if (scoped.length === 0) {
+        console.error(`no rules match --only ${only.join(', ')}`);
+        return 1;
+    }
+    if (format === 'ids') {
+        for (const heuristic of scoped) {
+            for (const rule of heuristic.rules) {
+                console.log(rule.id);
+            }
+        }
+        return 0;
+    }
+    if (format === 'json') {
+        console.log(JSON.stringify({
+            version: options.version,
+            scope: only.length > 0 ? only : 'all',
+            base,
+            alwaysInScope: await readAlwaysInScope(packagedSkillDir),
+            /** Rules "trunative detect" can raise a finding on, as source evidence. */
+            detectable: DETECTORS.map((detector) => detector.rule),
+            heuristics: scoped,
+        }, undefined, '\t'));
+        return 0;
+    }
+    process.stdout.write(markdown(all, scoped, base, options.version));
+    return 0;
+}

package/dist/commands/spec.js

@@ -0,0 +1,300 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readIndex, readIndexFiles } from '../heuristics.js';
+import { CONFIG_DIR, packagedSkillDir } from '../paths.js';
+/** The keys a screen brief carries, and no others. */
+const FIELDS = ['target', 'primary_action', 'states', 'scope'];
+/** The six `state-set` names, which are the six keys, always all six. */
+const STATES = ['loading', 'empty', 'error', 'offline', 'partial', 'permission'];
+/**
+ * What the brief may never carry. A number with a unit, or a line that reads
+ * like a declaration, is the layout format growing inside the brief, and
+ * `flow/spec.md` sends both to DESIGN.md.
+ */
+const MEASURED = /(^|[^a-z0-9])\d+(\.\d+)?\s?(px|pt|dp|sp|rem|em|%)\b/i;
+const DECLARED = /^\s*[-*]?\s*(padding|margin|gap|radius|border-radius|font-size|font-weight|line-height|width|height|spacing|shadow|opacity|elevation|z-index)\s*[:=]/i;
+const HEX = /#[0-9a-f]{6}\b/gi;
+const DASH = /[—–]/;
+function split(source) {
+    const lines = source.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---') {
+        return undefined;
+    }
+    const end = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (end === -1) {
+        return undefined;
+    }
+    return {
+        head: lines.slice(1, end),
+        offset: 2,
+        body: lines.slice(end + 1),
+        bodyOffset: end + 2,
+    };
+}
+/** Top-level `key: value` pairs, with the nested lines that belong to each. */
+function fields(head) {
+    const found = new Map();
+    let current;
+    head.forEach((line, index) => {
+        if (line.trim() === '' || line.trimStart().startsWith('#')) {
+            return;
+        }
+        const top = /^([a-z_]+):\s*(.*)$/.exec(line);
+        if (top) {
+            current = { value: top[2].trim(), line: index, children: [] };
+            found.set(top[1], current);
+            return;
+        }
+        current?.children.push(line);
+    });
+    return found;
+}
+/** `[a, b]` on the key's own line, or a block of `- a` under it. */
+function list(value, children) {
+    const inline = /^\[(.*)\]$/.exec(value);
+    if (inline) {
+        return inline[1]
+            .split(',')
+            .map((item) => item.trim())
+            .filter(Boolean);
+    }
+    return children
+        .map((line) => /^\s*-\s*(.+)$/.exec(line)?.[1]?.trim() ?? '')
+        .filter(Boolean);
+}
+/** `key: value` pairs nested one level under a parent. */
+function map(children) {
+    const found = [];
+    let indent = -1;
+    children.forEach((line, index) => {
+        const pair = /^(\s+)([a-z_]+):\s*(.*)$/.exec(line);
+        if (!pair) {
+            return;
+        }
+        const depth = pair[1].length;
+        if (indent === -1) {
+            indent = depth;
+        }
+        if (depth !== indent) {
+            return;
+        }
+        found.push({ key: pair[2], value: pair[3].trim(), line: index });
+    });
+    return found;
+}
+const PREFIX_ROW = /\|\s*`heuristics\/([a-z0-9-]+)\.md`\s*\|\s*`([a-z0-9-]+)`\s*\|/;
+/**
+ * Every spelling of an extra file, resolved to its stem. The Extra table prints
+ * the stem and the rule prefix side by side and they often differ, so a brief
+ * that says "l10n" for `heuristics/localization.md` is naming the row it read
+ * rather than making a mistake. `rubric --only` already takes either, and a
+ * checker stricter than the generator is a trap with no upside.
+ */
+async function stems(skillDir) {
+    const found = new Map();
+    for (const stem of await readIndexFiles(skillDir, 'extra')) {
+        found.set(stem, stem);
+    }
+    for (const line of await readIndex(skillDir, 'extra')) {
+        const row = PREFIX_ROW.exec(line);
+        if (!row) {
+            continue;
+        }
+        found.set(row[2], row[1]);
+        found.set(row[2].replace(/-$/, ''), row[1]);
+    }
+    return found;
+}
+/** How far a colour is from grey, 0 to 1. Tinted greys stay low, brand does not. */
+function chroma(hex) {
+    const channels = [1, 3, 5].map((at) => Number.parseInt(hex.slice(at, at + 2), 16));
+    return (Math.max(...channels) - Math.min(...channels)) / 255;
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkBrief(cwd, file, extra, base) {
+    const findings = [];
+    const add = (kind, detail, line) => {
+        findings.push({ kind, detail, file, line });
+    };
+    const source = await readFile(join(cwd, file), 'utf8');
+    source.split(/\r?\n/).forEach((line, index) => {
+        if (DASH.test(line)) {
+            add('dash', 'em dash or en dash', index + 1);
+        }
+    });
+    const brief = split(source);
+    if (!brief) {
+        add('frontmatter', 'no frontmatter fenced by --- on the first line', 1);
+        return findings;
+    }
+    for (const [index, line] of brief.body.entries()) {
+        const at = brief.bodyOffset + index;
+        if (MEASURED.test(line)) {
+            add('measured', 'a number with a unit, which belongs in DESIGN.md', at);
+        }
+        if (DECLARED.test(line)) {
+            add('measured', 'a style declaration, which belongs in DESIGN.md', at);
+        }
+    }
+    const head = fields(brief.head);
+    for (const name of FIELDS) {
+        if (!head.has(name)) {
+            add('missing field', name, brief.offset);
+        }
+    }
+    for (const [name, field] of head) {
+        if (!FIELDS.includes(name)) {
+            add('unknown field', name, brief.offset + field.line);
+        }
+    }
+    const target = head.get('target');
+    if (target) {
+        if (!target.value) {
+            add('target', 'empty, name the file that implements the screen', brief.offset + target.line);
+        }
+        else if (!(await exists(join(cwd, target.value)))) {
+            add('target', `${target.value} is not on disk`, brief.offset + target.line);
+        }
+    }
+    const action = head.get('primary_action');
+    if (action) {
+        const quoted = /^"(.+)"$/.exec(action.value);
+        if (!quoted) {
+            add('primary action', 'must be the label the user reads, in quotes, not an identifier', brief.offset + action.line);
+        }
+    }
+    const states = head.get('states');
+    if (states) {
+        const declared = map(states.children);
+        for (const name of STATES) {
+            if (!declared.some((entry) => entry.key === name)) {
+                add('state', `${name} is missing, and all six of state-set are required`, brief.offset + states.line);
+            }
+        }
+        for (const entry of declared) {
+            const at = brief.offset + states.line + 1 + entry.line;
+            if (!STATES.includes(entry.key)) {
+                add('state', `${entry.key} is not one of the six state-set names`, at);
+                continue;
+            }
+            if (!entry.value) {
+                add('state', `${entry.key} has no line saying what the screen shows`, at);
+                continue;
+            }
+            if (/^n\/a\b/i.test(entry.value) && entry.value.replace(/^n\/a\b[\s,.:;-]*/i, '') === '') {
+                add('state', `${entry.key} is n/a with no reason`, at);
+            }
+        }
+    }
+    const scope = head.get('scope');
+    if (scope) {
+        const at = brief.offset + scope.line;
+        const parts = map(scope.children);
+        const openAt = parts.find((entry) => entry.key === 'open');
+        const closedAt = parts.find((entry) => entry.key === 'closed');
+        const openChildren = scope.children.slice((openAt?.line ?? -1) + 1, closedAt?.line ?? undefined);
+        const open = openAt ? list(openAt.value, openChildren) : [];
+        const closed = closedAt ? map(scope.children.slice(closedAt.line + 1)) : [];
+        if (!openAt) {
+            add('scope', 'no open list, name the extra files this screen touches', at);
+        }
+        const opened = new Set();
+        for (const stem of open) {
+            if (base.includes(stem)) {
+                add('scope', `${stem} is a base file, which is opened on every screen`, at);
+                continue;
+            }
+            const canonical = extra.get(stem);
+            if (!canonical) {
+                add('scope', `${stem} is not a file in the Extra table`, at);
+                continue;
+            }
+            opened.add(canonical);
+        }
+        for (const entry of closed) {
+            const line = brief.offset + scope.line + 2 + closedAt.line + entry.line;
+            const canonical = extra.get(entry.key);
+            if (!canonical) {
+                add('scope', `${entry.key} is not a file in the Extra table`, line);
+            }
+            else if (opened.has(canonical)) {
+                add('scope', `${entry.key} is both open and closed`, line);
+            }
+            if (!entry.value) {
+                add('scope', `${entry.key} is closed with no reason`, line);
+            }
+        }
+    }
+    const wireframe = file.replace(/\.md$/, '.wireframe.html');
+    if (await exists(join(cwd, wireframe))) {
+        const drawing = await readFile(join(cwd, wireframe), 'utf8');
+        drawing.split(/\r?\n/).forEach((line, index) => {
+            for (const match of line.matchAll(HEX)) {
+                if (chroma(match[0]) > 0.1) {
+                    findings.push({
+                        kind: 'wireframe',
+                        detail: `${match[0]} is a colour, and a wireframe is greyscale`,
+                        file: wireframe,
+                        line: index + 1,
+                    });
+                }
+            }
+        });
+    }
+    return findings;
+}
+/**
+ * Checks the screen briefs in a project. It is the doctor's family rather than
+ * the lint's: it reads what the agent wrote into a consumer project, not the
+ * skill this package ships.
+ */
+export async function spec(options) {
+    const { cwd } = options;
+    const dir = join(CONFIG_DIR, 'screens');
+    let files = options.paths.map((path) => path.replace(/\\/g, '/'));
+    if (files.length === 0) {
+        try {
+            files = (await readdir(join(cwd, dir)))
+                .filter((name) => name.endsWith('.md'))
+                .sort()
+                .map((name) => `${dir}/${name}`);
+        }
+        catch {
+            files = [];
+        }
+    }
+    if (files.length === 0) {
+        console.log(`PASS  no screen briefs in ${dir}`);
+        console.log('      flow/spec.md writes one when a task changes structure.');
+        return 0;
+    }
+    const extra = await stems(packagedSkillDir);
+    const base = await readIndexFiles(packagedSkillDir, 'base');
+    const findings = [];
+    for (const file of files) {
+        if (!(await exists(join(cwd, file)))) {
+            findings.push({ kind: 'missing', detail: 'not on disk', file, line: 0 });
+            continue;
+        }
+        findings.push(...(await checkBrief(cwd, file, extra, base)));
+    }
+    if (findings.length === 0) {
+        console.log(`PASS  ${files.length} screen brief(s), 0 findings`);
+        return 0;
+    }
+    const width = Math.max(...findings.map((finding) => finding.kind.length));
+    for (const finding of findings) {
+        const where = `${finding.file}${finding.line ? `:${finding.line}` : ''}`;
+        console.log(`FAIL  ${finding.kind.padEnd(width)}  ${where}  ${finding.detail}`);
+    }
+    console.log(`\n${findings.length} finding(s) in ${files.length} screen brief(s).`);
+    return 1;
+}