@human-synthesis/norns-tron 0.0.1 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@human-synthesis/norns-tron",
-	"version": "0.0.1",
+	"version": "0.1.0",
 	"description": "TRON serialization for the Norns ecosystem — token-efficient, faster-than-JSON wire format for APIs and LLM-facing output.",
 	"license": "MIT",
 	"author": "Daniel Teodoroiu (https://humansynthesis.ai)",
@@ -24,6 +24,7 @@
 		"./server": "./src/server.js",
 		"./client": "./src/client.js",
 		"./valibot": "./src/valibot.js",
+		"./spec": "./src/spec.js",
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {

package/src/canonical.js

@@ -0,0 +1,113 @@
+/**
+ * Canonical pretty-printer for on-disk TRON spec files.
+ *
+ * The canonical form is the git-tracked representation of a Norns spec:
+ * deterministic (same value -> byte-identical text), line-oriented (one field
+ * per line so diffs and merges stay readable), and JSON-compatible (plain JSON
+ * is valid TRON, so `decode()` reads canonical files with zero special cases).
+ *
+ * Rules:
+ *   - JSON value semantics: `toJSON()` honored (Dates -> ISO strings),
+ *     `undefined` keys dropped, NaN/Infinity -> null — exactly JSON.stringify.
+ *   - Keys sorted: priority list first (spec-aware default), rest by codepoint.
+ *   - A node renders inline when its one-line form fits `maxInline` columns at
+ *     its indentation; otherwise one child per line. The rule is a pure
+ *     function of the value, so formatting never depends on prior state.
+ *   - 2-space indent, LF, single trailing newline.
+ */
+
+/**
+ * Spec-aware key ordering: identity and contract keys surface before bulk
+ * collections, so unit diffs lead with what a reviewer needs first. Unknown
+ * keys sort after all of these, alphabetically.
+ */
+export const SPEC_KEY_PRIORITY = [
+  // app / module identity
+  'module', 'depends', 'dialect', 'uid', 'name',
+  // unit contract essentials
+  'type', 'ref', 'from', 'route', 'owner', 'input', 'requires', 'transport',
+  'props', 'events', 'slots', 'live', 'groupBy',
+  // unit body
+  'fields', 'status', 'steps', 'emits', 'refresh', 'read', 'write',
+  'state', 'components', 'examples', 'impl', 'source', 'body',
+  // module collections (bulk, last)
+  'entities', 'queries', 'actions', 'policies', 'pages',
+  'triggers', 'functions', 'settings',
+];
+
+const DEFAULT_MAX_INLINE = 100;
+const DEFAULT_INDENT = 2;
+
+/**
+ * Format a value as canonical TRON text.
+ *
+ * @param {*} value anything JSON.stringify accepts
+ * @param {{indent?:number, maxInline?:number, keyPriority?:string[]}} [opts]
+ * @returns {string} canonical text, LF line endings, single trailing newline
+ */
+export function formatCanonical(value, opts) {
+  const o = opts || {};
+  const ctx = {
+    indent: ' '.repeat(o.indent === undefined ? DEFAULT_INDENT : o.indent),
+    maxInline: o.maxInline === undefined ? DEFAULT_MAX_INLINE : o.maxInline,
+    priority: buildPriority(o.keyPriority === undefined ? SPEC_KEY_PRIORITY : o.keyPriority),
+  };
+  // Normalize through JSON to inherit its value semantics exactly
+  // (toJSON, undefined-key dropping, NaN -> null, BigInt throws).
+  const json = JSON.stringify(value);
+  if (json === undefined) return 'null\n';
+  const tree = JSON.parse(json);
+  return render(tree, '', ctx) + '\n';
+}
+
+function buildPriority(list) {
+  const m = new Map();
+  for (let i = 0; i < list.length; i++) if (!m.has(list[i])) m.set(list[i], i);
+  return m;
+}
+
+function sortedKeys(node, priority) {
+  return Object.keys(node).sort((a, b) => {
+    const pa = priority.has(a) ? priority.get(a) : Infinity;
+    const pb = priority.has(b) ? priority.get(b) : Infinity;
+    if (pa !== pb) return pa - pb;
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+}
+
+function inline(node, ctx) {
+  if (node === null || typeof node !== 'object') return JSON.stringify(node);
+  if (Array.isArray(node)) {
+    if (node.length === 0) return '[]';
+    const parts = new Array(node.length);
+    for (let i = 0; i < node.length; i++) parts[i] = inline(node[i], ctx);
+    return '[' + parts.join(', ') + ']';
+  }
+  const keys = sortedKeys(node, ctx.priority);
+  if (keys.length === 0) return '{}';
+  const parts = new Array(keys.length);
+  for (let i = 0; i < keys.length; i++) {
+    parts[i] = JSON.stringify(keys[i]) + ': ' + inline(node[keys[i]], ctx);
+  }
+  return '{ ' + parts.join(', ') + ' }';
+}
+
+function render(node, pad, ctx) {
+  const flat = inline(node, ctx);
+  if (pad.length + flat.length <= ctx.maxInline) return flat;
+  if (node === null || typeof node !== 'object') return flat;
+  const childPad = pad + ctx.indent;
+  if (Array.isArray(node)) {
+    const items = new Array(node.length);
+    for (let i = 0; i < node.length; i++) {
+      items[i] = childPad + render(node[i], childPad, ctx);
+    }
+    return '[\n' + items.join(',\n') + '\n' + pad + ']';
+  }
+  const keys = sortedKeys(node, ctx.priority);
+  const items = new Array(keys.length);
+  for (let i = 0; i < keys.length; i++) {
+    items[i] = childPad + JSON.stringify(keys[i]) + ': ' + render(node[keys[i]], childPad, ctx);
+  }
+  return '{\n' + items.join(',\n') + '\n' + pad + '}';
+}

package/src/index.d.ts

@@ -87,6 +87,19 @@ export function defineSchema(spec: SchemaSpec): CompiledSchema;
 /** A registry for services serving several response shapes. */
 export function createRegistry(): SchemaRegistry;
 
+/**
+ * Format a value as canonical TRON text — the deterministic, line-oriented,
+ * JSON-compatible on-disk form used for spec files. Same value → byte-identical
+ * text; `decode()` reads it back with no special cases.
+ */
+export function formatCanonical(
+  value: unknown,
+  opts?: { indent?: number; maxInline?: number; keyPriority?: string[] }
+): string;
+
+/** Default key ordering for spec files: contract keys before bulk collections. */
+export const SPEC_KEY_PRIORITY: string[];
+
 /** True when the WASM fast path is usable here. */
 export function wasmAvailable(): boolean;
 

package/src/index.js

@@ -21,6 +21,7 @@ import * as ENCODER from './core/tron-encode.js';
 import * as AUTO from './core/tron-auto.js';
 import * as SCHEMA from './core/tron-schema.js';
 import * as WASM from './core/tron-wasm.js';
+import { formatCanonical, SPEC_KEY_PRIORITY } from './canonical.js';
 
 // Below this many bytes of equivalent JSON, the fixed costs of shape detection
 // dominate and plain JSON is simply faster and no smaller. Measured crossover
@@ -155,6 +156,8 @@ const raw = {
 export {
   encode,
   decode,
+  formatCanonical,
+  SPEC_KEY_PRIORITY,
   encodeColumnar,
   decodeColumnar,
   defineSchema,

package/src/spec.d.ts

@@ -0,0 +1,28 @@
+export const SPEC_EXT: '.tron';
+export const APP_SPEC: 'app';
+
+/** sha256 hex of a value's canonical text — the unit of change detection. */
+export function specHash(value: unknown): string;
+
+/** Decode one spec file (canonical or any TRON/JSON). */
+export function readSpec(file: string): unknown;
+
+/**
+ * Write a value to `file` in canonical form, creating parent dirs.
+ * No-op (changed: false) when on-disk bytes already match.
+ */
+export function writeSpec(
+  file: string,
+  value: unknown
+): { text: string; hash: string; changed: boolean };
+
+/** Read a whole `specs/` directory. */
+export function readSpecs(dir: string): {
+  app: unknown;
+  modules: Record<string, unknown>;
+  hashes: Record<string, string>;
+  version: string;
+};
+
+/** Combine per-module hashes into one deterministic app version hash. */
+export function combineHashes(hashes: Record<string, string>): string;

package/src/spec.js

@@ -0,0 +1,91 @@
+/**
+ * Spec-file helpers — server-side only (`@human-synthesis/norns-tron/spec`).
+ *
+ * A Norns app's canonical spec lives in `specs/` as one `.tron` file per
+ * module plus `app.tron`, written in canonical form (see canonical.js).
+ * These helpers read/write that directory and compute the content-addressed
+ * version hashes used by `ifVersion` optimistic checks and incremental
+ * generation.
+ */
+
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+import { formatCanonical } from './canonical.js';
+import * as AUTO from './core/tron-auto.js';
+
+export const SPEC_EXT = '.tron';
+export const APP_SPEC = 'app';
+
+/** sha256 hex of a value's canonical text — the unit of change detection. */
+export function specHash(value) {
+  return createHash('sha256').update(formatCanonical(value), 'utf-8').digest('hex');
+}
+
+/** Decode one spec file (canonical or any TRON/JSON). */
+export function readSpec(file) {
+  return AUTO.decode(readFileSync(file, 'utf-8'));
+}
+
+/**
+ * Write a value to `file` in canonical form, creating parent dirs.
+ * Skips the write when the on-disk bytes already match, so watchers and
+ * mtimes stay quiet on no-op applies.
+ *
+ * @returns {{ text: string, hash: string, changed: boolean }}
+ */
+export function writeSpec(file, value) {
+  const text = formatCanonical(value);
+  const hash = createHash('sha256').update(text, 'utf-8').digest('hex');
+  let existing = null;
+  try {
+    existing = readFileSync(file, 'utf-8');
+  } catch {
+    // new file
+  }
+  if (existing === text) return { text, hash, changed: false };
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, text, 'utf-8');
+  return { text, hash, changed: true };
+}
+
+/**
+ * Read a whole `specs/` directory.
+ *
+ * @param {string} dir
+ * @returns {{
+ *   app: *,                            // app.tron contents (null if absent)
+ *   modules: Record<string, *>,        // module name -> spec value
+ *   hashes: Record<string, string>,    // per-file canonical hash (incl. 'app')
+ *   version: string                    // hash over all files — the app version
+ * }}
+ */
+export function readSpecs(dir) {
+  const names = readdirSync(dir)
+    .filter((f) => f.endsWith(SPEC_EXT))
+    .sort();
+  const modules = {};
+  const hashes = {};
+  let app = null;
+  for (const f of names) {
+    const name = basename(f, SPEC_EXT);
+    const value = readSpec(join(dir, f));
+    hashes[name] = specHash(value);
+    if (name === APP_SPEC) app = value;
+    else modules[name] = value;
+  }
+  return { app, modules, hashes, version: combineHashes(hashes) };
+}
+
+/**
+ * Combine per-module hashes into one app version hash. Order-independent
+ * input, deterministic output.
+ */
+export function combineHashes(hashes) {
+  const h = createHash('sha256');
+  for (const name of Object.keys(hashes).sort()) {
+    h.update(name).update(':').update(hashes[name]).update('\n');
+  }
+  return h.digest('hex');
+}