trunative 1.0.0

package/dist/graph.js

@@ -0,0 +1,288 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { AGENTS, STACKS } from './compile.js';
+import { parseHeuristic, readIndex } from './heuristics.js';
+import { tokenize, values } from './mdx.js';
+import { packagedSkillDir } from './paths.js';
+const BACKTICKED = /`([a-z0-9][a-z0-9-]*)`/g;
+const REFERENCE = /`(references\/[a-z0-9-]+\.(?:md|json))`/g;
+const PREFIX_ROW = /\|\s*`heuristics\/([a-z0-9-]+)\.md`\s*\|\s*`([a-z0-9-]+)`\s*\|/;
+async function listDir(skillDir, dir) {
+    try {
+        return (await readdir(join(skillDir, dir)))
+            .filter((name) => !name.startsWith('.'))
+            .map((name) => `${dir}/${name}`)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Paths a SKILL.md index names, such as "flow/init.md". */
+function indexed(lines, dir) {
+    const found = [];
+    const pattern = new RegExp('`(' + dir + '/[a-z0-9-]+\\.(?:md|json))`', 'g');
+    for (const line of lines) {
+        for (const match of line.matchAll(pattern)) {
+            if (!found.includes(match[1])) {
+                found.push(match[1]);
+            }
+        }
+    }
+    return found;
+}
+/** Declared prefix per heuristics file, read from the base and extra tables. */
+function prefixes(lines) {
+    const found = new Map();
+    for (const line of lines) {
+        const row = PREFIX_ROW.exec(line);
+        if (row) {
+            found.set(row[1], row[2]);
+        }
+    }
+    return found;
+}
+export async function readGraph(skillDir = packagedSkillDir) {
+    const files = {
+        flow: await listDir(skillDir, 'flow'),
+        heuristics: await listDir(skillDir, 'heuristics'),
+        references: await listDir(skillDir, 'references'),
+    };
+    const baseLines = await readIndex(skillDir, 'base');
+    const extraLines = await readIndex(skillDir, 'extra');
+    const index = {
+        flow: indexed(await readIndex(skillDir, 'flow'), 'flow'),
+        base: indexed(baseLines, 'heuristics'),
+        extra: indexed(extraLines, 'heuristics'),
+        references: indexed(await readIndex(skillDir, 'references'), 'references'),
+    };
+    const alwaysLines = await readIndex(skillDir, 'always');
+    const always = [];
+    for (const line of alwaysLines) {
+        for (const match of line.matchAll(BACKTICKED)) {
+            if (match[1].includes('-') && !always.includes(match[1])) {
+                always.push(match[1]);
+            }
+        }
+    }
+    const declared = prefixes([...baseLines, ...extraLines]);
+    const heuristics = [];
+    for (const path of files.heuristics.filter((file) => file.endsWith('.md'))) {
+        const source = await readFile(join(skillDir, path), 'utf8');
+        heuristics.push(parseHeuristic(basename(path, '.md'), path, source, always));
+    }
+    const rules = heuristics.flatMap((heuristic) => heuristic.rules);
+    const ids = new Set(rules.map((rule) => rule.id));
+    /**
+     * A backticked token is a citation when it sits in the prefix namespace the
+     * index declares. Everything else in backticks is a platform constant, and
+     * `email-address` is not a broken link to a rule nobody wrote.
+     */
+    const namespace = [...declared.values()];
+    const cites = (token) => !namespace.includes(token) && namespace.some((prefix) => token.startsWith(prefix));
+    const everyFile = ['SKILL.md', ...files.flow, ...files.heuristics, ...files.references];
+    const mentions = [];
+    const links = [];
+    const tags = [];
+    for (const path of everyFile.filter((file) => file.endsWith('.md'))) {
+        const source = await readFile(join(skillDir, path), 'utf8');
+        let section;
+        for (const token of tokenize(source)) {
+            if (token.type === 'tag') {
+                tags.push({ tag: token.tag, file: path });
+                if (token.tag.name === 'Rule') {
+                    section = token.tag.attributes['id'];
+                }
+            }
+            const text = token.type === 'text' ? token.text : token.tag.content;
+            const line = token.type === 'text' ? token.line : token.tag.line;
+            for (const match of text.matchAll(BACKTICKED)) {
+                const id = match[1];
+                if (ids.has(id) || cites(id)) {
+                    mentions.push({ id, file: path, line: line + 1, ...(section ? { from: section } : {}) });
+                }
+            }
+            for (const match of text.matchAll(REFERENCE)) {
+                links.push({ target: match[1], file: path, line: line + 1 });
+            }
+        }
+    }
+    return {
+        heuristics,
+        rules,
+        mentions,
+        links,
+        files,
+        index,
+        always,
+        tags,
+        findings: check({ heuristics, rules, mentions, links, files, index, always, tags, declared }),
+    };
+}
+/** Where each tag is allowed to appear, by directory. */
+const PLACEMENT = {
+    Rule: (file) => file.startsWith('heuristics/'),
+    Check: (file) => file.startsWith('heuristics/'),
+    Verify: (file) => file.startsWith('heuristics/'),
+    Device: (file) => file.startsWith('heuristics/'),
+    If: (file) => file.startsWith('flow/') || file.startsWith('references/'),
+    Ask: (file) => file.startsWith('flow/'),
+    Option: (file) => file.startsWith('flow/'),
+    Index: (file) => file === 'SKILL.md',
+};
+const ATTRIBUTES = {
+    Rule: ['id', 'evidence', 'description'],
+    Check: ['against'],
+    Verify: ['rule'],
+    Device: [],
+    If: ['agent', 'stack'],
+    Ask: ['header'],
+    Option: [],
+    Index: ['of'],
+};
+const INDEX_VALUES = ['flow', 'base', 'extra', 'always', 'references'];
+const STACK_VALUES = [...STACKS, 'other', 'undecided'];
+function check(input) {
+    const findings = [];
+    const add = (kind, detail, file, line) => {
+        findings.push({ kind, detail, ...(file ? { file } : {}), ...(line ? { line } : {}) });
+    };
+    const ids = new Set(input.rules.map((rule) => rule.id));
+    for (const rule of input.rules) {
+        if (rule.line === 0) {
+            add('check without rule', `\`${rule.id}\` is verified but never defined`, `heuristics/${rule.file}.md`, rule.checkLine);
+        }
+        if (rule.checkLine === 0) {
+            add('rule without check', `\`${rule.id}\` has no Verify line`, `heuristics/${rule.file}.md`, rule.line);
+        }
+        if (!rule.title) {
+            add('rule without description', `\`${rule.id}\``, `heuristics/${rule.file}.md`, rule.line);
+        }
+        const prefix = input.declared.get(rule.file);
+        if (prefix && !rule.id.startsWith(prefix)) {
+            add('prefix', `\`${rule.id}\` does not start with \`${prefix}\``, `heuristics/${rule.file}.md`, rule.line);
+        }
+    }
+    for (const mention of input.mentions) {
+        if (!ids.has(mention.id)) {
+            add('dangling id', `\`${mention.id}\` is defined nowhere`, mention.file, mention.line);
+        }
+    }
+    for (const id of input.always) {
+        if (!ids.has(id)) {
+            add('always in scope', `\`${id}\` is listed in SKILL.md and defined nowhere`, 'SKILL.md');
+        }
+    }
+    const base = input.index.base.map((path) => basename(path, '.md'));
+    for (const id of input.always) {
+        const owner = input.rules.find((rule) => rule.id === id);
+        if (owner && !base.includes(owner.file)) {
+            add('always in scope', `\`${id}\` lives in ${owner.file}, which is not a base file`, 'SKILL.md');
+        }
+    }
+    const listed = new Set([...input.index.flow, ...input.index.base, ...input.index.extra, ...input.index.references]);
+    for (const group of ['flow', 'heuristics', 'references']) {
+        for (const file of input.files[group]) {
+            if (!listed.has(file)) {
+                add('not indexed', `${file} exists and no index in SKILL.md lists it`, 'SKILL.md');
+            }
+        }
+        for (const file of group === 'heuristics' ? [...input.index.base, ...input.index.extra] : input.index[group]) {
+            if (!input.files[group].includes(file)) {
+                add('indexed and missing', `SKILL.md lists ${file} and it is not on disk`, 'SKILL.md');
+            }
+        }
+    }
+    for (const file of input.index.references) {
+        if (!input.links.some((link) => link.target === file && link.file !== 'SKILL.md')) {
+            add('unlinked reference', `${file} is listed and nothing points at it`, 'SKILL.md');
+        }
+    }
+    for (const link of input.links) {
+        if (!input.files.references.includes(link.target)) {
+            add('dangling link', `${link.target} does not exist`, link.file, link.line);
+        }
+    }
+    const open = [];
+    for (const { tag, file } of input.tags) {
+        const allowed = PLACEMENT[tag.name];
+        if (!allowed) {
+            add('unknown tag', `<${tag.name}>`, file, tag.line + 1);
+            continue;
+        }
+        if (!allowed(file)) {
+            add('tag in the wrong place', `<${tag.name}> in ${file}`, file, tag.line + 1);
+        }
+        for (const name of Object.keys(tag.attributes)) {
+            if (!ATTRIBUTES[tag.name].includes(name)) {
+                add('unknown attribute', `${name} on <${tag.name}>`, file, tag.line + 1);
+            }
+        }
+        if (tag.name === 'If' && tag.kind === 'open') {
+            const agent = values(tag.attributes['agent']);
+            const stack = values(tag.attributes['stack']);
+            if (agent.length > 0 && stack.length > 0) {
+                add('If', 'carries both agent and stack', file, tag.line + 1);
+            }
+            if (agent.length === 0 && stack.length === 0) {
+                add('If', 'carries neither agent nor stack', file, tag.line + 1);
+            }
+            for (const value of agent) {
+                if (!AGENTS.includes(value)) {
+                    add('unknown agent', value, file, tag.line + 1);
+                }
+            }
+            for (const value of stack) {
+                if (!STACK_VALUES.includes(value)) {
+                    add('unknown stack', value, file, tag.line + 1);
+                }
+            }
+        }
+        if (tag.name === 'Index') {
+            const of = tag.attributes['of'] ?? '';
+            if (!INDEX_VALUES.includes(of)) {
+                add('unknown index', of, file, tag.line + 1);
+            }
+        }
+        if (tag.name === 'Ask' && tag.kind === 'open') {
+            const header = tag.attributes['header'] ?? '';
+            if (!header) {
+                add('Ask', 'has no header', file, tag.line + 1);
+            }
+            else if (header.length > 12) {
+                add('Ask', `header "${header}" is longer than 12 characters`, file, tag.line + 1);
+            }
+        }
+        if (tag.name === 'Rule' && tag.attributes['evidence'] && tag.attributes['evidence'] !== 'device') {
+            add('Rule', `evidence="${tag.attributes['evidence']}" is not a value`, file, tag.line + 1);
+        }
+        if (tag.kind === 'open') {
+            open.push({ tag, file });
+        }
+        else if (tag.kind === 'close') {
+            const last = open.pop();
+            if (!last || last.tag.name !== tag.name) {
+                add('unbalanced tag', `</${tag.name}> closes ${last ? `<${last.tag.name}>` : 'nothing'}`, file, tag.line + 1);
+            }
+        }
+    }
+    for (const { tag, file } of open) {
+        add('unbalanced tag', `<${tag.name}> is never closed`, file, tag.line + 1);
+    }
+    for (const of of INDEX_VALUES) {
+        const count = input.tags.filter((entry) => entry.tag.name === 'Index' && entry.tag.attributes['of'] === of).length;
+        if (count !== 1) {
+            add('index marker', `<Index of="${of}" /> appears ${count} times, expected once`, 'SKILL.md');
+        }
+    }
+    const options = input.tags.filter((entry) => entry.tag.name === 'Option' && entry.tag.kind === 'open');
+    const recommended = options.filter((entry) => entry.tag.flags.includes('recommended'));
+    if (options.length > 0 && recommended.length > 1) {
+        add('Ask', `${recommended.length} options are marked recommended`, recommended[1].file);
+    }
+    return findings;
+}
+/** Every id the skill defines, in file order. Used by the detector registry. */
+export function ruleIds(graph) {
+    return graph.rules.map((rule) => rule.id);
+}

package/dist/heuristics.js

@@ -0,0 +1,185 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { tokenize } from './mdx.js';
+/** A rule heading: `## <Rule id="touch-floor" evidence="device" description="..." />`. */
+const HEADING = /^## <Rule\s+([^>]*?)\s*\/>\s*$/;
+const ATTRIBUTE = /([a-z]+)="([^"]*)"/g;
+const CHECK_LINE = /^- (.*?)\s*`([a-z0-9-]+)`\s*$/;
+function attributes(source) {
+    const found = {};
+    for (const match of source.matchAll(ATTRIBUTE)) {
+        found[match[1]] = match[2];
+    }
+    return found;
+}
+/**
+ * The lines of the list an <Index of="..." /> marker in SKILL.md announces,
+ * up to the next heading or the next marker. Empty when the marker is absent.
+ */
+export async function readIndex(skillDir, of) {
+    let source;
+    try {
+        source = await readFile(join(skillDir, 'SKILL.md'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const lines = source.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.trim() === `<Index of="${of}" />`);
+    if (start === -1) {
+        return [];
+    }
+    const found = [];
+    for (const line of lines.slice(start + 1)) {
+        if (line.startsWith('#') || line.trim().startsWith('<Index ')) {
+            break;
+        }
+        found.push(line);
+    }
+    return found;
+}
+/** Ids listed under the "always" index in SKILL.md. */
+export async function readAlwaysInScope(skillDir) {
+    const ids = [];
+    for (const line of await readIndex(skillDir, 'always')) {
+        if (!line.startsWith('- ')) {
+            continue;
+        }
+        for (const match of line.matchAll(/`([a-z0-9-]+)`/g)) {
+            const id = match[1];
+            if (id.includes('-') && !ids.includes(id)) {
+                ids.push(id);
+            }
+        }
+    }
+    return ids;
+}
+/** File stems listed under one of the file indexes in SKILL.md, such as "base". */
+export async function readIndexFiles(skillDir, of) {
+    const stems = [];
+    for (const line of await readIndex(skillDir, of)) {
+        for (const match of line.matchAll(/`heuristics\/([a-z0-9-]+)\.md`/g)) {
+            if (!stems.includes(match[1])) {
+                stems.push(match[1]);
+            }
+        }
+    }
+    return stems;
+}
+export function parseHeuristic(file, path, source, always) {
+    const lines = source.split(/\r?\n/);
+    const rules = [];
+    const order = new Map();
+    const title = lines.find((line) => line.startsWith('# '))?.slice(2).trim() ?? file;
+    lines.forEach((line, index) => {
+        const heading = HEADING.exec(line);
+        if (!heading) {
+            return;
+        }
+        const attrs = attributes(heading[1]);
+        const id = attrs['id'];
+        if (!id) {
+            return;
+        }
+        const rule = {
+            id,
+            title: attrs['description'] ?? '',
+            check: '',
+            file,
+            always: always.includes(id),
+            line: index + 1,
+            checkLine: 0,
+            evidence: attrs['evidence'] === 'device' ? 'device' : 'source',
+        };
+        rules.push(rule);
+        order.set(rule.id, rule);
+    });
+    const device = [];
+    for (const token of tokenize(source)) {
+        if (token.type !== 'tag' || token.tag.kind !== 'inline') {
+            continue;
+        }
+        if (token.tag.name === 'Device') {
+            device.push(token.tag.content);
+            continue;
+        }
+        if (token.tag.name !== 'Verify') {
+            continue;
+        }
+        const id = token.tag.attributes['rule'] ?? '';
+        const known = order.get(id);
+        if (known) {
+            known.check = token.tag.content;
+            known.checkLine = token.tag.line + 1;
+            continue;
+        }
+        const rule = {
+            id,
+            title: '',
+            check: token.tag.content,
+            file,
+            always: always.includes(id),
+            line: 0,
+            checkLine: token.tag.line + 1,
+            evidence: 'source',
+        };
+        rules.push(rule);
+        order.set(id, rule);
+    }
+    const start = rules.some((rule) => rule.checkLine > 0)
+        ? -1
+        : lines.findIndex((line) => line.trim() === '## Check');
+    if (start !== -1) {
+        let seenBullet = false;
+        for (let index = start + 1; index < lines.length; index += 1) {
+            const line = lines[index];
+            if (line.startsWith('## ')) {
+                break;
+            }
+            const check = CHECK_LINE.exec(line);
+            if (check) {
+                seenBullet = true;
+                const id = check[2];
+                const known = order.get(id);
+                if (known) {
+                    known.check = check[1];
+                    known.checkLine = index + 1;
+                }
+                else {
+                    const rule = {
+                        id,
+                        title: '',
+                        check: check[1],
+                        file,
+                        always: always.includes(id),
+                        line: 0,
+                        checkLine: index + 1,
+                        evidence: 'source',
+                    };
+                    rules.push(rule);
+                    order.set(id, rule);
+                }
+                continue;
+            }
+            if (seenBullet && line.trim() !== '') {
+                device.push(line.trim());
+            }
+        }
+    }
+    return { file, path, title, rules, device: device.join(' ') };
+}
+/** Every heuristics file in the skill, in filename order. */
+export async function readHeuristics(skillDir) {
+    const dir = join(skillDir, 'heuristics');
+    const names = (await readdir(dir))
+        .filter((name) => name.endsWith('.md'))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const always = await readAlwaysInScope(skillDir);
+    const heuristics = [];
+    for (const name of names) {
+        const source = await readFile(join(dir, name), 'utf8');
+        const file = basename(name, '.md');
+        heuristics.push(parseHeuristic(file, `heuristics/${name}`, source, always));
+    }
+    return heuristics;
+}

package/dist/lock.js

@@ -0,0 +1,18 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONFIG_DIR, LOCK_FILE } from './paths.js';
+export function lockPath(cwd) {
+    return join(cwd, CONFIG_DIR, LOCK_FILE);
+}
+export async function readLock(cwd) {
+    try {
+        return JSON.parse(await readFile(lockPath(cwd), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeLock(cwd, lock) {
+    await mkdir(join(cwd, CONFIG_DIR), { recursive: true });
+    await writeFile(lockPath(cwd), `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
+}

package/dist/mdx.js

@@ -0,0 +1,84 @@
+/**
+ * The tag syntax the skill is written in. Every tag sits alone on its line,
+ * optionally behind a heading marker, and nothing inside a fenced code block is
+ * a tag. This module is the only place that knows the grammar.
+ */
+const TAG_LINE = /^(#{1,6}\s+)?<\s*(\/?)\s*([A-Z][A-Za-z]*)\s*([^>]*?)\s*(\/?)>\s*$/;
+/** One line that opens, fills and closes a tag: <Verify rule="x">text</Verify>. */
+const INLINE_LINE = /^(#{1,6}\s+)?<([A-Z][A-Za-z]*)\s*([^>]*?)>(.+)<\/\2>\s*$/;
+const ATTRIBUTE = /([a-zA-Z-]+)(?:="([^"]*)")?/g;
+const FENCE = /^\s*(```|~~~)/;
+function parseAttributes(source) {
+    const attributes = {};
+    const flags = [];
+    for (const match of source.matchAll(ATTRIBUTE)) {
+        if (match[2] === undefined) {
+            flags.push(match[1]);
+        }
+        else {
+            attributes[match[1]] = match[2];
+        }
+    }
+    return { attributes, flags };
+}
+/** Every line of the file, with the tag lines parsed. Code fences pass as text. */
+export function tokenize(source) {
+    const tokens = [];
+    let fence = '';
+    source.split(/\r?\n/).forEach((text, line) => {
+        const opener = FENCE.exec(text);
+        if (fence) {
+            if (opener && text.trim().startsWith(fence)) {
+                fence = '';
+            }
+            tokens.push({ type: 'text', line, text });
+            return;
+        }
+        if (opener) {
+            fence = opener[1];
+            tokens.push({ type: 'text', line, text });
+            return;
+        }
+        const inline = INLINE_LINE.exec(text);
+        if (inline) {
+            tokens.push({
+                type: 'tag',
+                tag: {
+                    line,
+                    name: inline[2],
+                    kind: 'inline',
+                    prefix: inline[1] ?? '',
+                    content: inline[4].trim(),
+                    ...parseAttributes(inline[3] ?? ''),
+                },
+            });
+            return;
+        }
+        const match = TAG_LINE.exec(text);
+        if (!match) {
+            tokens.push({ type: 'text', line, text });
+            return;
+        }
+        const closing = match[2] === '/';
+        const self = match[5] === '/';
+        tokens.push({
+            type: 'tag',
+            tag: {
+                line,
+                name: match[3],
+                kind: closing ? 'close' : self ? 'self' : 'open',
+                prefix: match[1] ?? '',
+                content: '',
+                ...parseAttributes(match[4] ?? ''),
+            },
+        });
+    });
+    return tokens;
+}
+/** Comma separated attribute values, such as agent="codex, antigravity". */
+export function values(attribute) {
+    return (attribute ?? '')
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+}

package/dist/paths.js

@@ -0,0 +1,62 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Root of the installed trunative package, resolved from this module. */
+export const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+/**
+ * The skill as it is written, with its tags still in it. It sits under "src"
+ * because a skill index walks the repository root one level deep and the
+ * "skills" directory three: a source tree named "skills" is served as a skill,
+ * tags and all. Nested under "src" it is out of both walks.
+ */
+export const packagedSkillDir = join(packageRoot, 'src', 'skills');
+/**
+ * Where "trunative build" writes the resolved copies. Inside it the layout is
+ * the one a project has, so ".claude/skills/trunative-flutter" here is the same
+ * path it lands on there.
+ */
+export const compiledSkillsDir = join(packageRoot, 'dist', 'agents');
+/**
+ * The published copies, in the flat layout a skill index reads. One directory
+ * per stack variant, resolved for the "other" agent, because an index hands
+ * every harness the same bytes and "other" is the branch that names no harness.
+ */
+export const publishedSkillsDir = join(packageRoot, 'skills');
+/** The agent a published copy resolves. See publishedSkillsDir. */
+export const PUBLISHED_AGENT = 'other';
+/**
+ * The directory each agent reads in a project. Zed and anything else reading
+ * the shared root gets the "other" build, which resolves no harness branch.
+ */
+export const AGENT_DIR = {
+    claude: '.claude',
+    codex: '.codex',
+    antigravity: '.antigravity',
+    opencode: '.opencode',
+    other: '.agents',
+};
+/** "trunative" for the generic copy, "trunative-flutter" for a stack variant. */
+export function variantName(name, stack) {
+    return stack ? `${name}-${stack}` : name;
+}
+/** Where trunative keeps its own files inside a consumer project. */
+export const CONFIG_DIR = '.trunative';
+export const LOCK_FILE = 'skill.lock';
+/**
+ * Agent roots we install into. Only the ones that already exist in the project
+ * are used, so we never create a directory for an agent the user does not have.
+ */
+export const AGENT_ROOTS = ['.claude', '.agents', '.antigravity', '.codex', '.opencode'];
+/** Used when the project has no agent directory at all. */
+export const DEFAULT_AGENT_ROOT = '.claude';
+/** The agent whose branches a directory's copy resolves. */
+export function agentFor(root) {
+    const found = Object.entries(AGENT_DIR).find(([, dir]) => dir === root);
+    return found ? found[0] : 'other';
+}
+/**
+ * Both places a brief may live, in priority order. The bare filename is
+ * supported so a project can keep the briefs next to its README.
+ */
+export function briefCandidates(cwd, file) {
+    return [join(cwd, CONFIG_DIR, file), join(cwd, file)];
+}