@n8r/surface 0.1.0-experimental.2 → 0.1.0-experimental.5

package/dist/cyclonedx-validation.d.ts

@@ -0,0 +1 @@
+export declare function validateBom(bom: unknown): void;

package/dist/cyclonedx-validation.js

@@ -0,0 +1,45 @@
+/** Standard validation shared by the legacy reader and BOM authority. */
+import { Ajv } from 'ajv';
+import formats from 'ajv-formats';
+import extendedFormats from 'ajv-formats-draft2019';
+import bomSchema from './cyclonedx-schemas/bom-1.7.schema.json' with { type: 'json' };
+import cryptoSchema from './cyclonedx-schemas/cryptography-defs.schema.json' with { type: 'json' };
+import spdxSchema from './cyclonedx-schemas/spdx.schema.json' with { type: 'json' };
+import jsfSchema from './cyclonedx-schemas/jsf-0.82.schema.json' with { type: 'json' };
+function refuse() { throw Error('CycloneDX 1.7 schema/reference validation failed. Input values withheld.'); }
+function guard(fn) { try {
+    return fn();
+}
+catch {
+    return refuse();
+} }
+const ajv = new Ajv({ strict: false, allErrors: false, validateFormats: true });
+// ajv-formats CJS interop is normalized by Node and the standalone bundler.
+formats(ajv);
+extendedFormats(ajv);
+// The upstream IRI checker rejects URNs because uri-js parses their NSS
+// separately from path. Accept only the standard BOM-Link grammar here.
+const iriReference = ajv.formats['iri-reference'];
+ajv.addFormat('iri-reference', (value) => /^urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[1-9][0-9]*(?:#[^\s]+)?$/.test(value) || iriReference(value));
+ajv.addSchema(spdxSchema);
+ajv.addSchema(jsfSchema);
+ajv.addSchema(cryptoSchema);
+const schemaCheck = ajv.compile(bomSchema);
+export function validateBom(bom) {
+    guard(() => {
+        if (!schemaCheck(bom))
+            refuse();
+        const b = bom;
+        if (b.bomFormat !== 'CycloneDX' || b.specVersion !== '1.7')
+            refuse();
+        const refs = new Set();
+        for (const n of [...(b.components ?? []), ...(b.services ?? [])]) {
+            if (typeof n['bom-ref'] !== 'string' || refs.has(n['bom-ref']))
+                refuse();
+            refs.add(n['bom-ref']);
+        }
+        for (const d of b.dependencies ?? [])
+            if (!refs.has(d.ref) || d.dependsOn?.some((r) => !refs.has(r)))
+                refuse();
+    });
+}

package/dist/html.js

@@ -1,6 +1,7 @@
-import { decode, encode } from './codec.js';
-import { checkSize, fail } from './portable.js';
-import { validateArtefact } from './validate.js';
+import { decode, encode, decodeJsonValue } from './codec.js';
+import { checkSize, fail, canonical } from './portable.js';
+import { validateArtefact, verifyReferences } from './validate.js';
+import { renderBundleHtml } from './skill-presentation.js';
 const escape = (text) => text.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
 function display(value) {
     if (Array.isArray(value))
@@ -44,6 +45,29 @@ export function readResearchHtml(html) {
     const record = decode(blocks[0][1], 'json');
     if (record.contract !== 'n8r.research/0.1')
         fail('$html', 'requires research record');
+    if (html.includes('<meta name="n8r-presentation" content="1">')) {
+        const contexts = [...html.matchAll(/<script type="application\/json" id="n8r-context">([\s\S]*?)<\/script>/g)];
+        if (contexts.length !== 1)
+            fail('$html', 'requires exactly one presentation context');
+        const context = decodeJsonValue(contexts[0][1]);
+        if (!context || Object.keys(context).sort().join(',') !== 'dependencies,surface' || !Array.isArray(context.dependencies))
+            fail('$html', 'invalid presentation context');
+        const surface = validateArtefact(context.surface);
+        if (surface.contract !== 'n8r.surface/0.3')
+            fail('$html', 'requires Surface 0.3');
+        const dependencies = context.dependencies.map(validateArtefact);
+        const all = [record, surface, ...dependencies].filter((a, i, items) => {
+            const first = items.findIndex(x => x.id === a.id && x.revision.id === a.revision.id);
+            if (canonical(items[first]) !== canonical(a))
+                fail('$html', 'ambiguous presentation revision');
+            return first === i;
+        });
+        for (const item of all)
+            verifyReferences(item, all);
+        if (renderBundleHtml({ research: record, surface, dependencies }) !== html)
+            fail('$html', 'HTML/data conflict');
+        return record;
+    }
     if (renderResearchHtml(record) !== html)
         fail('$html', 'HTML/data conflict; preserve bytes and review the edit before regenerating');
     return record;

package/dist/recent.d.ts

@@ -0,0 +1,9 @@
+export type RecentWork = {
+    id: string;
+    title: string;
+    source: string;
+    path: string;
+    model: string;
+};
+export declare function recentWork(home: string): RecentWork[];
+export declare function rememberWork(home: string, item: RecentWork): void;

package/dist/recent.js

@@ -0,0 +1,71 @@
+/** Local navigation metadata only; never included in portable research artifacts. */
+import fs from 'node:fs';
+import { join, resolve, relative, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { InspectionError, readBytes } from './settings.js';
+function location(home) {
+    const directory = join(fs.realpathSync(home), '.n8r');
+    try {
+        const stat = fs.lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new InspectionError('Recent-work folder is not a regular directory');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    return { directory, file: join(directory, 'recent.json') };
+}
+function valid(item) {
+    return item && ['id', 'title', 'source', 'path', 'model'].every(k => typeof item[k] === 'string' && item[k].length > 0 && item[k].length < 16000)
+        && resolve(item.source) === item.source && resolve(item.path) === item.path;
+}
+export function recentWork(home) {
+    const { file } = location(home);
+    let bytes;
+    try {
+        bytes = readBytes(file, 1024 * 1024);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new InspectionError('Recent-work list is damaged; saved research is unchanged');
+    }
+    if (!Array.isArray(value) || value.length > 100 || !value.every(valid))
+        throw new InspectionError('Invalid recent-work list; saved research is unchanged');
+    return value;
+}
+export function rememberWork(home, item) {
+    if (!valid(item))
+        throw new InspectionError('Invalid saved-work reference');
+    const { directory, file } = location(home);
+    const rel = relative(item.source, directory);
+    if (!rel || (!rel.startsWith(`..${sep}`) && rel !== '..' && !rel.startsWith(sep)))
+        throw new InspectionError('Recent-work list cannot be written inside the research source');
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const lock = file + '.lock';
+    const fd = fs.openSync(lock, 'wx', 0o600);
+    const temporary = file + '.' + randomUUID();
+    try {
+        const previous = recentWork(home);
+        const next = [item, ...previous.filter(p => p.id !== item.id)].slice(0, 100);
+        fs.writeFileSync(temporary, JSON.stringify(next, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        // Check again while holding our lock; refuse user edits during this save.
+        if (JSON.stringify(recentWork(home)) !== JSON.stringify(previous))
+            throw new InspectionError('Recent-work list changed; saved research is unchanged');
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        fs.closeSync(fd);
+        fs.unlinkSync(lock);
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}

package/dist/revisions.js

@@ -8,6 +8,48 @@ export function verifySuccessor(previous, next) {
     const parent = after.revision.parent;
     if (!parent || parent.id !== before.id || parent.revision !== before.revision.id || parent.digest !== digest(before) || after.revision.id === before.revision.id)
         fail('$revision', 'parent revision/digest mismatch or reused revision');
+    if (before.contract === 'n8r.surface/0.2' && after.contract === 'n8r.surface/0.2') {
+        if (before.kind !== after.kind)
+            fail('$revision', 'description kind changed');
+        for (const n of after.nodes) {
+            const old = before.nodes.find(x => x.id === n.id);
+            if (old && canonical(old.type) !== canonical(n.type))
+                fail('$revision', 'retained node type changed');
+        }
+        if (before.kind === 'capability' && after.kind === 'capability') {
+            for (const c of after.capabilities) {
+                const old = before.capabilities.find(x => x.id === c.id);
+                if (old && (old.from !== c.from || old.to !== c.to || canonical(old.type) !== canonical(c.type)))
+                    fail('$revision', 'retained capability endpoints/type changed');
+            }
+        }
+        if (before.kind === 'bound' && after.kind === 'bound') {
+            if (before.instance.id !== after.instance.id || before.capability.id !== after.capability.id)
+                fail('$revision', 'instance/capability identity changed');
+            for (const b of after.bindings) {
+                const old = before.bindings.find(x => x.id === b.id);
+                if (old && old.capability !== b.capability)
+                    fail('$revision', 'retained binding slot changed');
+            }
+        }
+    }
+    if (before.contract === 'n8r.surface/0.3' && after.contract === 'n8r.surface/0.3') {
+        if (before.kind !== after.kind)
+            fail('$revision', 'description kind changed');
+        for (const n of after.nodes) {
+            const old = before.nodes.find(x => x.id === n.id);
+            if (old && canonical(old.type) !== canonical(n.type))
+                fail('$revision', 'retained node type changed');
+        }
+        for (const edge of after.relationships) {
+            const old = before.relationships.find(x => x.id === edge.id);
+            if (old && (old.from !== edge.from || old.to !== edge.to || canonical(old.type) !== canonical(edge.type)))
+                fail('$revision', 'retained relationship endpoints/type changed');
+        }
+        if (before.kind === 'bound' && after.kind === 'bound' &&
+            (before.instance.id !== after.instance.id || before.capability.id !== after.capability.id))
+            fail('$revision', 'instance/capability identity changed');
+    }
     if (before.contract === 'n8r.surface/0.1' && after.contract === 'n8r.surface/0.1') {
         for (const edge of after.relationships) {
             const old = before.relationships.find(x => x.id === edge.id);

package/dist/skill-artifacts-cli.d.ts

@@ -0,0 +1 @@
+export * from './skill-artifacts.js';

package/dist/skill-artifacts-cli.js

@@ -0,0 +1,13 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { main } from './skill-artifacts.js';
+export * from './skill-artifacts.js';
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    try {
+        main(process.argv.slice(2));
+    }
+    catch {
+        console.error('Surface operation failed. Check input contracts, privacy, references, predecessor and destination; no success claimed.');
+        process.exitCode = 1;
+    }
+}

package/dist/skill-artifacts.d.ts

@@ -0,0 +1,15 @@
+import type { Artefact, ResearchRecord, SurfaceGraph } from './contracts.js';
+export interface Bundle {
+    research: ResearchRecord;
+    surface: SurfaceGraph;
+    dependencies: Artefact[];
+}
+/** Conservative defense in depth; host must omit sensitive values before staging. */
+export declare function privacy(value: unknown): void;
+export declare function checkBundle(input: unknown): Bundle;
+export declare function readBundle(directory: string): Bundle;
+export declare function verifyBundleSuccessor(parent: Bundle, b: Bundle): void;
+export declare function saveBundle(input: unknown, destination: string, predecessor?: string): Bundle;
+export declare function main(args: string[]): void;
+/** Same canonical digest, with value-free diagnostics at the skill boundary. */
+export declare function digest(value: unknown): string;

package/dist/skill-artifacts.js

@@ -0,0 +1,184 @@
+/** Standalone installed-skill persistence. No CLI, runner, network or source reads. */
+import fs from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { decode, encode, decodeJsonValue } from './codec.js';
+import { validateArtefact, verifyReferences } from './validate.js';
+import { digest as artifactDigest, canonical } from './portable.js';
+import { readResearchHtml, renderResearchHtml } from './html.js';
+import { renderBrief, renderBundleHtml } from './skill-presentation.js';
+import { verifySuccessor } from './revisions.js';
+const members = ['research.html', 'surface.json', 'dependencies.json', 'brief.md'];
+const hash = (s) => `sha256:${createHash('sha256').update(s).digest('hex')}`;
+function fail(code) { throw new Error(`Surface operation refused: ${code}. No input values are included.`); }
+function guarded(code, fn) { try {
+    return fn();
+}
+catch {
+    return fail(code);
+} }
+/** Conservative defense in depth; host must omit sensitive values before staging. */
+export function privacy(value) {
+    const text = canonical(value);
+    if (/(?:https?|mongodb(?:\+srv)?|postgres(?:ql)?):\/\/|\b(?:\d{1,3}\.){3}\d{1,3}\b|\b(?:[a-f0-9]{1,4}:){2,}[a-f0-9:]+\b|(?:password|passwd|token|secret|username|api[_-]?key)\s*[=:]\s*[^\s"},]+|(?:\/Users\/|\/home\/|[A-Z]:\\\\)|[\w.+-]+@[\w.-]+\.[a-z]{2,}/i.test(text))
+        fail('privacy review required');
+}
+export function checkBundle(input) {
+    return guarded('bundle validation or privacy check', () => {
+        if (!input || typeof input !== 'object' || Object.keys(input).sort().join(',') !== 'dependencies,research,surface')
+            fail('bundle shape');
+        const b = input;
+        privacy(b);
+        const research = validateArtefact(b.research), surface = validateArtefact(b.surface);
+        if (research.contract !== 'n8r.research/0.1' || surface.contract !== 'n8r.surface/0.3' || !Array.isArray(b.dependencies) || b.dependencies.length > 100)
+            fail('contracts');
+        const context = [];
+        for (const a of [research, surface, ...b.dependencies.map(validateArtefact)]) {
+            if (Object.keys(a.extensions).length)
+                fail('opaque extensions unsupported by this host');
+            const old = context.find(x => x.id === a.id && x.revision.id === a.revision.id);
+            if (old && digest(old) !== digest(a))
+                fail('ambiguous revision');
+            if (!old)
+                context.push(a);
+        }
+        if (!surface.records.some(r => r.id === research.id && r.revision === research.revision.id && r.digest === digest(research)))
+            fail('unlinked research');
+        for (const a of context)
+            verifyReferences(a, context);
+        return { research, surface, dependencies: b.dependencies };
+    });
+}
+function directories(dir) {
+    for (let p = resolve(dir);; p = dirname(p)) {
+        if (fs.existsSync(p)) {
+            const s = fs.lstatSync(p);
+            if (s.isSymbolicLink() || !s.isDirectory())
+                fail('unsafe directory');
+        }
+        else {
+            try {
+                fs.lstatSync(p);
+                fail('unsafe directory');
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw e;
+            }
+        }
+        if (p === dirname(p))
+            break;
+    }
+}
+function read(path) {
+    const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > 8 * 1024 * 1024)
+            fail('file size/type');
+        return new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(fd));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+const plain = (s) => s.replace(/[\r\n]/g, ' ').replace(/[<>\[\]`|]/g, '');
+function brief(b) {
+    const s = b.surface, name = (id) => plain(s.nodes.find(n => n.id === id)?.label ?? id);
+    return `# ${plain(s.title)}\n\n${s.kind === 'bound' ? 'Bound' : 'Capability'} Surface · ${plain(s.revision.id)}\n\n${plain(s.scope)}\n\n` +
+        s.relationships.map(e => {
+            const state = 'binding' in e ? e.binding.state : e.state;
+            const target = 'binding' in e ? e.binding.claims.map(c => name(c.target)).join(', ') : 'supported possibility';
+            const detail = (d) => `${d.state}: ${d.claims.map(c => plain(c.value)).join(' / ') || plain(d.note)}`;
+            return `- **${name(e.from)} → ${name(e.to)}** (role endpoints; ${state})\n  Target: ${target || 'unknown'}. Purpose: ${detail(e.purpose)}. Integration: ${detail(e.integration)}.\n`;
+        }).join('') + `\n## Evidence and decisions\n\nSee research.html for exact sources, findings, competing claims and human decisions; surface.json retains property-level evidence and configuration references. Configured does not establish runtime use.\n\n## Gaps\n\n${s.gaps.map(g => '- ' + plain(g)).join('\n') || 'No additional gaps recorded; coverage remains bounded.'}\n\n## Recommended next steps\n\n${b.research.questions.map(q => '- ' + plain(q.text)).join('\n') || 'Review the evidence and confirm the next question before expanding coverage.'}\n`;
+}
+export function readBundle(directory) {
+    return guarded('saved-byte verification', () => {
+        directory = resolve(directory);
+        directories(directory);
+        const m = JSON.parse(read(join(directory, 'manifest.json')));
+        if (![1, 2].includes(m.version) || Object.keys(m.files ?? {}).sort().join(',') !== [...members].sort().join(','))
+            fail('manifest');
+        if (fs.readdirSync(directory).sort().join(',') !== [...members, 'manifest.json'].sort().join(','))
+            fail('unexpected members');
+        const data = Object.fromEntries(members.map(n => { const text = read(join(directory, n)); if (hash(text) !== m.files[n])
+            fail('changed bytes'); return [n, text]; }));
+        const b = checkBundle({ research: readResearchHtml(data['research.html']), surface: decode(data['surface.json'], 'json'), dependencies: decodeJsonValue(data['dependencies.json']) });
+        if (data['brief.md'] !== (m.version === 1 ? brief(b) : renderBrief(b)))
+            fail('brief conflict');
+        if (data['research.html'] !== (m.version === 1 ? renderResearchHtml(b.research) : renderBundleHtml(b)))
+            fail('presentation context conflict');
+        return b;
+    });
+}
+export function verifyBundleSuccessor(parent, b) {
+    for (const old of [parent.research, parent.surface, ...parent.dependencies]) {
+        const next = [b.research, b.surface, ...b.dependencies].find(a => a.id === old.id && a.revision.id === old.revision.id);
+        if (next && digest(next) !== digest(old))
+            fail('rewritten pinned revision');
+    }
+    verifySuccessor(parent.research, b.research);
+    verifySuccessor(parent.surface, b.surface);
+    for (const d of parent.research.decisions)
+        if (!b.research.decisions.some(n => canonical(n) === canonical(d)))
+            fail('lost human decision');
+    for (const n of parent.surface.nodes)
+        if (!b.surface.nodes.some(x => x.id === n.id))
+            fail('lost component identity');
+}
+export function saveBundle(input, destination, predecessor) {
+    return guarded('save validation, predecessor or destination check', () => {
+        const b = checkBundle(input);
+        destination = resolve(destination);
+        directories(dirname(destination));
+        const parent = predecessor ? readBundle(predecessor) : undefined;
+        const previousBytes = predecessor ? read(join(predecessor, 'manifest.json')) : undefined;
+        if (parent) {
+            verifyBundleSuccessor(parent, b);
+        }
+        else if (b.research.revision.parent || b.surface.revision.parent)
+            fail('predecessor required');
+        const data = { 'research.html': renderBundleHtml(b), 'surface.json': encode(b.surface, 'json'), 'dependencies.json': JSON.stringify(b.dependencies, null, 2) + '\n', 'brief.md': renderBrief(b) };
+        const manifest = JSON.stringify({ version: 2, files: Object.fromEntries(members.map(n => [n, hash(data[n])])), predecessor: previousBytes ? hash(previousBytes) : null }, null, 2) + '\n';
+        // Parent must exist; exclusive mkdir never replaces an occupied destination.
+        fs.mkdirSync(destination, { mode: 0o700 });
+        try {
+            for (const [name, bytes] of Object.entries({ ...data, 'manifest.json': manifest }))
+                fs.writeFileSync(join(destination, name), bytes, { flag: 'wx', mode: 0o600 });
+            const result = readBundle(destination);
+            if (predecessor) {
+                readBundle(predecessor);
+                if (read(join(predecessor, 'manifest.json')) !== previousBytes)
+                    fail('predecessor changed');
+            }
+            return result;
+        }
+        catch (e) {
+            // Retain incomplete output for inspection; never call it a successful save.
+            throw e;
+        }
+    });
+}
+export function main(args) {
+    const [op, file, destination, previous] = args;
+    if (op === 'help' && args.length === 1) {
+        console.log('Standalone Surface helper: check BUNDLE.json | save BUNDLE.json NEW_DIRECTORY [PREDECESSOR_DIRECTORY] | read DIRECTORY. JSON bundle: {research,surface,dependencies}. Save only with user authorization. Node 22/24/26; no network or n8r-surface CLI.');
+        return;
+    }
+    if (op === 'read' && args.length === 2) {
+        const b = readBundle(file);
+        console.log(JSON.stringify({ status: 'checked', kind: b.surface.kind, research: b.research, surface: b.surface, dependencies: b.dependencies }, null, 2));
+        return;
+    }
+    if ((op === 'check' && args.length === 2) || (op === 'save' && (args.length === 3 || args.length === 4))) {
+        const b = checkBundle(decodeJsonValue(read(file)));
+        if (op === 'save')
+            saveBundle(b, destination, previous);
+        console.log(JSON.stringify({ status: op === 'save' ? 'saved-and-read-back' : 'checked', kind: b.surface.kind, researchDigest: digest(b.research), surfaceDigest: digest(b.surface) }));
+        return;
+    }
+    fail('arguments; run help');
+}
+/** Same canonical digest, with value-free diagnostics at the skill boundary. */
+export function digest(value) { return guarded('digest input', () => artifactDigest(value)); }

package/dist/skill-cyclonedx.d.ts

@@ -0,0 +1,26 @@
+import type { Bundle } from './skill-artifacts.js';
+export interface MappingNode {
+    id: string;
+    kind: 'component' | 'service';
+    type?: string;
+    rationale: string;
+}
+export interface Mapping {
+    nodes: MappingNode[];
+    dependencies: string[];
+}
+type Bom = Record<string, any>;
+export interface Exchange {
+    bundle: Bundle;
+    mapping: Mapping;
+    bom: Bom;
+    report: Record<string, any>;
+    predecessor: string | null;
+}
+export { validateBom } from './cyclonedx-validation.js';
+export declare function projectBundle(input: unknown, mapping: unknown, previous?: Exchange): {
+    bom: Bom;
+    report: Record<string, any>;
+};
+export declare function readExchange(directory: string): Exchange;
+export declare function saveExchange(bundleDirectory: string, mapping: unknown, destination: string, previousDirectory?: string): Exchange;