@n8r/surface 0.0.0-stage → 0.1.0-experimental.5

package/dist/settings.js

@@ -0,0 +1,100 @@
+import { constants, openSync, closeSync, fstatSync, readSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/** Escape terminal controls and line/bidi separators in untrusted labels. */
+export function line(value) {
+    return value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, c => `\\u${c.codePointAt(0).toString(16).padStart(4, '0')}`);
+}
+export class InspectionError extends Error {
+}
+export function problem(error) {
+    if (error instanceof InspectionError)
+        return error.message;
+    const code = error?.code;
+    return typeof code === 'string' && /^[A-Z0-9_]+$/.test(code) ? code : 'Read failed';
+}
+/** Do not block on special files, follow entry symlinks or read unbounded data. */
+export function readBytes(path, limit) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new InspectionError('Not a regular file');
+        if (stat.size > limit)
+            throw new InspectionError(`File exceeds ${limit} bytes`);
+        const buffer = Buffer.alloc(limit + 1);
+        let bytes = 0;
+        while (bytes < buffer.length) {
+            const count = readSync(fd, buffer, bytes, buffer.length - bytes, null);
+            if (!count)
+                break;
+            bytes += count;
+        }
+        if (bytes > limit)
+            throw new InspectionError(`File exceeds ${limit} bytes`);
+        return buffer.subarray(0, bytes);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function settings(text, home, file) {
+    let data = { version: 1 };
+    if (text !== undefined) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new InspectionError('Invalid JSON; repair the existing file');
+        }
+    }
+    if (!object(data) || data.version !== 1)
+        throw new InspectionError('Expected settings object with version 1');
+    const path = localPath(data.artefactRoot === undefined ? '~/n8r/artefacts' : data.artefactRoot, home, dirname(file));
+    const vault = data.vaultRoot === undefined ? undefined : localPath(data.vaultRoot, home, dirname(file));
+    const format = data.surfaceFormat === undefined ? 'json' : data.surfaceFormat;
+    if (format !== 'json' && format !== 'yaml')
+        throw new InspectionError('surfaceFormat must be json or yaml');
+    for (const key of ['runner', 'lab']) {
+        if (data[key] !== undefined && data[key] !== null && !object(data[key]))
+            throw new InspectionError(`${key} must be an object or null`);
+    }
+    return {
+        home, file, original: undefined, data, vault, root: path,
+        format, defaultRoot: data.artefactRoot === undefined, defaultFormat: data.surfaceFormat === undefined,
+        runner: object(data.runner), lab: object(data.lab)
+    };
+}
+export function localPath(value, home, base) {
+    if (typeof value !== 'string' || !value.trim() || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value) || /^[a-z][a-z0-9+.-]*:/i.test(value) || (value.startsWith('~') && !value.startsWith('~/'))) {
+        throw new InspectionError('Expected a local path, optionally starting with ~/');
+    }
+    return value.startsWith('~/') ? resolve(home, value.slice(2)) : resolve(base, value);
+}
+export function readLocal(path, limit) {
+    return readBytes(path, limit).toString('utf8');
+}
+export function loadSettings(home = homedir()) {
+    const file = join(home, '.n8r/n8r-surface.json');
+    let original;
+    try {
+        original = readBytes(file, 64 * 1024);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        // A dangling symlink is not an absent settings file.
+        try {
+            lstatSync(file);
+            throw new InspectionError('Settings is not a regular file');
+        }
+        catch (entryError) {
+            if (entryError.code !== 'ENOENT')
+                throw entryError;
+        }
+    }
+    return { ...settings(original?.toString('utf8'), home, file), original };
+}

package/dist/setup.d.ts

@@ -0,0 +1,9 @@
+import { type Settings } from './settings.js';
+export declare function chooseVault(value: string, home: string, cwd: string): string;
+/** Read-only validation: missing folders need consent, occupied paths are errors. */
+export declare function inspectVault(root: string): {
+    root: string;
+    missing: boolean;
+};
+/** Called only after explicit acceptance. See startup.md for the writer boundary. */
+export declare function saveSetup(snapshot: Settings, selected: string, cwd: string): string;

package/dist/setup.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { InspectionError, loadSettings, localPath } from './settings.js';
+const children = ['research', 'artifacts', 'surfaces'];
+/** Resolve existing ancestors as well as explicitly chosen root symlinks. */
+function canonical(path) {
+    try {
+        return fs.realpathSync(path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        // Reject dangling symlinks rather than treating them as new directories.
+        try {
+            fs.lstatSync(path);
+            throw new InspectionError('Dangling symlink');
+        }
+        catch (entryError) {
+            if (entryError.code !== 'ENOENT')
+                throw entryError;
+        }
+        const parent = dirname(path);
+        if (parent === path)
+            throw error;
+        return join(canonical(parent), path.slice(parent.length));
+    }
+}
+export function chooseVault(value, home, cwd) {
+    return localPath(canonical(localPath(value, home, cwd)), home, cwd);
+}
+/** Read-only validation: missing folders need consent, occupied paths are errors. */
+export function inspectVault(root) {
+    root = canonical(root);
+    let missing = false;
+    for (const path of [root, ...children.map(child => join(root, child))]) {
+        try {
+            const stat = fs.lstatSync(path);
+            if (stat.isSymbolicLink())
+                throw new InspectionError('Vault children cannot be symlinks');
+            if (!stat.isDirectory())
+                throw new InspectionError('Vault path is not a directory');
+            fs.accessSync(path, fs.constants.R_OK | fs.constants.X_OK);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            missing = true;
+        }
+    }
+    return { root, missing };
+}
+function inside(path, source) {
+    const part = relative(source, canonical(path));
+    return part === '' || (part !== '..' && !part.startsWith(`..${sep}`) && !part.startsWith(sep));
+}
+function unchanged(snapshot) {
+    const current = loadSettings(snapshot.home).original;
+    if (snapshot.original === undefined ? current !== undefined : current === undefined || !snapshot.original.equals(current)) {
+        throw new InspectionError('Settings changed; setup conflict. Restart and review the saved values.');
+    }
+}
+/** Called only after explicit acceptance. See startup.md for the writer boundary. */
+export function saveSetup(snapshot, selected, cwd) {
+    const vault = inspectVault(chooseVault(selected, snapshot.home, cwd)).root;
+    const source = canonical(resolve(cwd));
+    const file = snapshot.file;
+    for (const path of [dirname(file), file, vault, ...children.map(child => join(vault, child))]) {
+        if (inside(path, source))
+            throw new InspectionError('Setup would write inside the source; choose a separate vault or source directory.');
+    }
+    if (snapshot.vault !== undefined && canonical(snapshot.vault) !== vault)
+        throw new InspectionError('Configured vault cannot be changed by setup');
+    const legacy = canonical(snapshot.root);
+    for (const child of children) {
+        const path = join(vault, child);
+        if (canonical(path) !== legacy && inside(path, legacy)) {
+            throw new InspectionError('Vault folders would occupy the legacy artefact corpus; choose a separate vault.');
+        }
+    }
+    // Keep unknown JSON member bytes, including numbers outside JS precision/range.
+    // The validated original is an object containing version, so a comma is valid.
+    let output = Buffer.alloc(0);
+    if (snapshot.vault === undefined) {
+        if (snapshot.original === undefined) {
+            output = Buffer.from(JSON.stringify({ version: 1, vaultRoot: vault }, null, 2) + '\n');
+        }
+        else {
+            const end = snapshot.original.lastIndexOf(0x7d);
+            output = Buffer.concat([snapshot.original.subarray(0, end),
+                Buffer.from(`,\n  "vaultRoot": ${JSON.stringify(vault)}\n`), snapshot.original.subarray(end)]);
+        }
+    }
+    if (output.length > 64 * 1024)
+        throw new InspectionError('Updated settings exceeds 65536 bytes');
+    fs.mkdirSync(dirname(file), { recursive: true });
+    const lock = file + '.lock';
+    let lockFd;
+    try {
+        lockFd = fs.openSync(lock, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new InspectionError('Setup lock exists; another setup may be in progress. See startup documentation for stale-lock recovery.');
+        throw error;
+    }
+    let temporary;
+    try {
+        unchanged(snapshot);
+        fs.mkdirSync(vault, { recursive: true });
+        for (const child of children) {
+            const path = join(vault, child);
+            try {
+                fs.mkdirSync(path);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            const stat = fs.lstatSync(path);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new InspectionError('Vault child is occupied or a symlink');
+        }
+        inspectVault(vault);
+        unchanged(snapshot);
+        if (snapshot.vault === undefined) {
+            const candidate = file + '.' + randomUUID() + '.tmp';
+            const fd = fs.openSync(candidate, 'wx', 0o600);
+            temporary = candidate;
+            try {
+                fs.writeFileSync(fd, output);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            unchanged(snapshot);
+            if (snapshot.original === undefined)
+                fs.linkSync(temporary, file);
+            else
+                fs.renameSync(temporary, file);
+        }
+        return vault;
+    }
+    finally {
+        try {
+            if (temporary !== undefined) {
+                try {
+                    fs.unlinkSync(temporary);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+        }
+        finally {
+            fs.closeSync(lockFd);
+            fs.unlinkSync(lock);
+        }
+    }
+}

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;