janux 0.1.0

package/src/runtime/intents.ts

@@ -0,0 +1,121 @@
+import { validate } from '../schema';
+import { allowMutations } from '../state/mutation-gate';
+import type { ComponentDef, Ctx, GuardValue, IntentDef, Origin, RunBag } from '../define/types';
+
+export interface AuditEntry {
+  tool: string;
+  origin: Origin;
+  guard: GuardValue;
+  input: unknown;
+  ok: boolean;
+  error?: string;
+  at: number;
+}
+
+export interface Proposal {
+  id: string;
+  tool: string;
+  input: unknown;
+  execute: () => Promise<unknown>;
+}
+
+export interface IntentHooks {
+  onAudit?: (entry: AuditEntry) => void;
+  onProposal?: (proposal: Proposal) => void;
+  trackPending: <T>(work: Promise<T>) => Promise<T>;
+}
+
+export class JanuxIntentError extends Error {
+  readonly code: 'forbidden' | 'not_ready' | 'invalid_input' | 'unknown_intent';
+
+  constructor(code: JanuxIntentError['code'], message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function resolveGuard(def: IntentDef, ctx: Ctx): GuardValue {
+  const guard = def.guard ?? 'auto';
+
+  return typeof guard === 'function' ? guard({ ctx }) : guard;
+}
+
+let proposalSeq = 0;
+
+function nextProposalId(tool: string): string {
+  proposalSeq += 1;
+
+  return `prop_${tool.replace(/\W/g, '_')}_${proposalSeq}`;
+}
+
+function checkInvocable(tool: string, def: IntentDef, bag: RunBag): void {
+  if (def.ready && !def.ready(bag)) {
+    throw new JanuxIntentError('not_ready', `Intent "${tool}" is not ready`);
+  }
+}
+
+function parseInput(tool: string, def: IntentDef, input: unknown): unknown {
+  if (!def.input) return undefined;
+  const result = validate(def.input, input ?? {});
+
+  if (!result.ok) {
+    const detail = result.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+
+    throw new JanuxIntentError('invalid_input', `Invalid input for "${tool}" — ${detail}`);
+  }
+
+  return result.value;
+}
+
+function audit(hooks: IntentHooks, entry: Omit<AuditEntry, 'at'>): void {
+  hooks.onAudit?.({ ...entry, at: Date.now() });
+}
+
+async function execute(def: IntentDef, bag: RunBag, input: unknown): Promise<unknown> {
+  return allowMutations(() => def.run({ ...bag, input }));
+}
+
+function propose(tool: string, input: unknown, run: () => Promise<unknown>, hooks: IntentHooks) {
+  const proposal: Proposal = { id: nextProposalId(tool), tool, input, execute: run };
+
+  hooks.onProposal?.(proposal);
+
+  return { status: 'proposal' as const, id: proposal.id, tool, input };
+}
+
+/** The single invocation pipeline shared by human clicks, agent calls and RPC. */
+export async function invokeIntent(
+  componentName: string,
+  intentName: string,
+  def: IntentDef,
+  bag: RunBag,
+  input: unknown,
+  origin: Origin,
+  hooks: IntentHooks,
+): Promise<unknown> {
+  const tool = `${componentName}.${intentName}`;
+  const guard = resolveGuard(def, bag.ctx);
+
+  try {
+    if (origin === 'agent' && guard === 'forbidden') {
+      throw new JanuxIntentError('forbidden', `Intent "${tool}" is not available`);
+    }
+    checkInvocable(tool, def, bag);
+    const parsed = parseInput(tool, def, input);
+    const run = () => hooks.trackPending(execute(def, bag, parsed));
+
+    if (origin === 'agent' && guard === 'confirm') {
+      audit(hooks, { tool, origin, guard, input: parsed, ok: true });
+
+      return propose(tool, parsed, run, hooks);
+    }
+    const result = await run();
+
+    audit(hooks, { tool, origin, guard, input: parsed, ok: true });
+
+    return result;
+  } catch (error) {
+    audit(hooks, { tool, origin, guard, input, ok: false, error: String(error) });
+    throw error;
+  }
+}

package/src/runtime/settled.ts

@@ -0,0 +1,56 @@
+import { effect, signal } from '../signals';
+
+export interface PendingTracker {
+  track<T>(work: Promise<T>): Promise<T>;
+  add(): () => void;
+  readonly count: number;
+  settled(): Promise<void>;
+}
+
+/**
+ * Counts in-flight async work (sources loading, effects running, debounce
+ * timers). `settled()` resolves when the count reaches zero — the primitive
+ * behind `ui.settled()` (RFC §5.4).
+ */
+export function createPendingTracker(): PendingTracker {
+  const count = signal(0);
+
+  const add = (): (() => void) => {
+    count.value = count.peek() + 1;
+    let done = false;
+
+    return () => {
+      if (done) return;
+      done = true;
+      count.value = count.peek() - 1;
+    };
+  };
+
+  const track = <T>(work: Promise<T>): Promise<T> => {
+    const done = add();
+
+    return work.finally(done);
+  };
+
+  const settled = (): Promise<void> => {
+    return new Promise((resolve) => {
+      const dispose = effect(() => {
+        if (count.value > 0) return;
+        queueMicrotask(() => {
+          if (count.peek() > 0) return;
+          dispose();
+          resolve();
+        });
+      });
+    });
+  };
+
+  return {
+    track,
+    add,
+    settled,
+    get count() {
+      return count.peek();
+    },
+  };
+}

package/src/runtime/sources.ts

@@ -0,0 +1,92 @@
+import { signal } from '../signals';
+import type { Ctx, SourceDef, SourceReader } from '../define/types';
+import type { EventBus } from './bus';
+import type { PendingTracker } from './settled';
+
+export interface SourcesRuntime {
+  readers: Record<string, SourceReader & { refresh: () => Promise<void> }>;
+  start: () => void;
+  dispose: () => void;
+}
+
+function createOne(
+  def: SourceDef,
+  ctx: Ctx,
+  bus: EventBus,
+  tracker: PendingTracker,
+  cleanups: (() => void)[],
+  initial: { value: unknown } | undefined,
+) {
+  const value = signal<unknown>(initial?.value);
+  const pending = signal(initial === undefined);
+  const error = signal<unknown>(null);
+
+  const load = async (): Promise<void> => {
+    pending.value = true;
+    await tracker.track(
+      Promise.resolve()
+        .then(() => def.query({ ctx }))
+        .then((result) => {
+          value.value = result;
+          error.value = null;
+        })
+        .catch((cause) => {
+          error.value = cause;
+        })
+        .finally(() => {
+          pending.value = false;
+        }),
+    );
+  };
+
+  const start = (): void => {
+    if (initial === undefined) load().catch(() => {});
+    if (def.refresh?.everyMs) {
+      const interval = setInterval(() => load().catch(() => {}), def.refresh.everyMs);
+
+      cleanups.push(() => clearInterval(interval));
+    }
+    def.refresh?.events.forEach((event) => {
+      cleanups.push(bus.on(event, () => load().catch(() => {})));
+    });
+  };
+
+  const reader = {
+    get value() {
+      return value.value;
+    },
+    get pending() {
+      return pending.value;
+    },
+    get error() {
+      return error.value;
+    },
+    refresh: load,
+  };
+
+  return { reader, start };
+}
+
+/**
+ * Wires declared sources: async load with pending/error, timers and event
+ * refresh. `initialValues` (from the SSR snapshot) skip the first load —
+ * resumed islands never double-fetch what the server already loaded.
+ */
+export function createSources(
+  defs: Record<string, SourceDef> | undefined,
+  ctx: Ctx,
+  bus: EventBus,
+  tracker: PendingTracker,
+  initialValues?: Record<string, { value: unknown }>,
+): SourcesRuntime {
+  const cleanups: (() => void)[] = [];
+  const entries = Object.entries(defs ?? {}).map(([name, def]) => {
+    return [name, createOne(def, ctx, bus, tracker, cleanups, initialValues?.[name])] as const;
+  });
+
+  return {
+    readers: Object.fromEntries(entries.map(([name, one]) => [name, one.reader])),
+    start: () => entries.forEach(([, one]) => one.start()),
+    dispose: () => cleanups.forEach((cleanup) => cleanup()),
+  };
+}

package/src/schema/builders.ts

@@ -0,0 +1,46 @@
+import { JxType } from './types';
+
+export type Shape = Record<string, JxType>;
+export type ShapeOrType = JxType | Shape;
+
+function toType(input: ShapeOrType): JxType {
+  return input instanceof JxType ? input : obj(input);
+}
+
+export function str(): JxType {
+  return new JxType('string');
+}
+
+export function int(): JxType {
+  return new JxType('int');
+}
+
+export function num(): JxType {
+  return new JxType('number');
+}
+
+export function bool(): JxType {
+  return new JxType('boolean');
+}
+
+/** Monetary amount in minor units (cents). Serializes as integer. */
+export function money(): JxType {
+  return new JxType('money');
+}
+
+export function enums(values: readonly string[]): JxType {
+  return new JxType('enum', { values });
+}
+
+export function list(itemOrShape: ShapeOrType): JxType {
+  return new JxType('list', { item: toType(itemOrShape) });
+}
+
+export function obj(shape: Shape): JxType {
+  return new JxType('object', { shape });
+}
+
+/** Root schema for component/store state and intent/api inputs. */
+export function schema(shape: Shape): JxType {
+  return obj(shape);
+}

package/src/schema/defaults.ts

@@ -0,0 +1,33 @@
+import type { JxType } from './types';
+
+const ZERO_VALUES: Record<string, unknown> = {
+  string: '',
+  int: 0,
+  money: 0,
+  number: 0,
+  boolean: false,
+};
+
+/**
+ * Builds the initial value for a schema: explicit `.default()` wins, then
+ * `null` for nullables, `[]` for lists, recursion for objects, first value
+ * for enums, and the kind's zero value for primitives.
+ */
+export function buildDefault(type: JxType): unknown {
+  if (type.flags.defaultValue !== undefined) return type.flags.defaultValue;
+  if (type.flags.nullable) return null;
+  if (type.kind === 'list') return [];
+  if (type.kind === 'enum') return type.values![0];
+  if (type.kind === 'object') return buildObjectDefault(type);
+
+  return ZERO_VALUES[type.kind];
+}
+
+function buildObjectDefault(type: JxType): Record<string, unknown> {
+  const entries = Object.entries(type.shape!).map(([key, fieldType]) => [
+    key,
+    buildDefault(fieldType),
+  ]);
+
+  return Object.fromEntries(entries);
+}

package/src/schema/index.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  bool,
+  buildDefault,
+  enums,
+  int,
+  list,
+  money,
+  obj,
+  schema,
+  str,
+  toJsonSchema,
+  validate,
+} from './index';
+
+const cartSchema = schema({
+  items: list({ productId: str(), qty: int().min(1), unitPrice: money() }),
+  coupon: str().nullable(),
+});
+
+describe('schema validate', () => {
+  it('accepts a valid cart and applies structure', () => {
+    const input = { items: [{ productId: 'p1', qty: 2, unitPrice: 1999 }], coupon: null };
+    const result = validate(cartSchema, input);
+
+    expect(result.ok).toBe(true);
+    expect(result.value).toEqual(input);
+  });
+
+  it('rejects wrong primitive kinds with paths', () => {
+    const result = validate(cartSchema, { items: [{ productId: 1, qty: 'x', unitPrice: 1 }] });
+
+    expect(result.ok).toBe(false);
+    expect(result.errors.map((e) => e.path)).toContain('items[0].productId');
+    expect(result.errors.map((e) => e.path)).toContain('items[0].qty');
+  });
+
+  it('enforces min bounds', () => {
+    const result = validate(cartSchema, { items: [{ productId: 'p', qty: 0, unitPrice: 1 }] });
+
+    expect(result.ok).toBe(false);
+    expect(result.errors[0]!.message).toBe('below min 1');
+  });
+
+  it('applies defaults and strips unknown keys', () => {
+    const type = schema({ qty: int().default(1), name: str() });
+    const result = validate(type, { name: 'a', hacked: true });
+
+    expect(result.value).toEqual({ qty: 1, name: 'a' });
+  });
+
+  it('handles nullable, optional and required', () => {
+    expect(validate(str().nullable(), null).ok).toBe(true);
+    expect(validate(str(), null).ok).toBe(false);
+    expect(validate(str().optional(), undefined).ok).toBe(true);
+    expect(validate(str(), undefined).ok).toBe(false);
+  });
+
+  it('validates enums', () => {
+    const type = enums(['pending', 'paid']);
+
+    expect(validate(type, 'paid').ok).toBe(true);
+    expect(validate(type, 'nope').ok).toBe(false);
+  });
+});
+
+describe('schema defaults', () => {
+  it('builds zero-values, nullables and nested structures', () => {
+    expect(buildDefault(cartSchema)).toEqual({ items: [], coupon: null });
+    expect(buildDefault(schema({ a: int(), b: bool(), c: enums(['x', 'y']) }))).toEqual({
+      a: 0,
+      b: false,
+      c: 'x',
+    });
+  });
+
+  it('prefers explicit defaults', () => {
+    expect(buildDefault(int().default(5))).toBe(5);
+  });
+});
+
+describe('schema toJsonSchema', () => {
+  it('serializes nested schemas with required lists', () => {
+    const json = toJsonSchema(cartSchema) as any;
+
+    expect(json.type).toBe('object');
+    expect(json.required).toEqual(['items', 'coupon']);
+    expect(json.properties.items.items.properties.qty).toEqual({ type: 'integer', minimum: 1 });
+    expect(json.properties.coupon.type).toEqual(['string', 'null']);
+  });
+
+  it('marks money format and defaults', () => {
+    expect(toJsonSchema(money())).toEqual({ type: 'integer', format: 'money-minor-units' });
+    expect((toJsonSchema(int().default(3)) as any).default).toBe(3);
+  });
+
+  it('serializes plain obj same as schema', () => {
+    expect(toJsonSchema(obj({ a: str() }))).toEqual(toJsonSchema(schema({ a: str() })));
+  });
+});

package/src/schema/index.ts

@@ -0,0 +1,5 @@
+export { JxType, type JxKind, type JxFlags } from './types';
+export { str, int, num, bool, money, enums, list, obj, schema, type Shape } from './builders';
+export { validate, type JxResult, type JxError } from './validate';
+export { buildDefault } from './defaults';
+export { toJsonSchema } from './json-schema';

package/src/schema/json-schema.ts

@@ -0,0 +1,42 @@
+import type { JxType } from './types';
+
+const PRIMITIVE_TYPES: Record<string, string> = {
+  string: 'string',
+  int: 'integer',
+  money: 'integer',
+  number: 'number',
+  boolean: 'boolean',
+};
+
+function baseSchema(type: JxType): Record<string, unknown> {
+  if (type.kind === 'enum') return { enum: [...type.values!] };
+  if (type.kind === 'list') return { type: 'array', items: toJsonSchema(type.item!) };
+  if (type.kind === 'object') return objectSchema(type);
+
+  return { type: PRIMITIVE_TYPES[type.kind] };
+}
+
+function objectSchema(type: JxType): Record<string, unknown> {
+  const shape = type.shape!;
+  const properties = Object.fromEntries(
+    Object.entries(shape).map(([key, field]) => [key, toJsonSchema(field)]),
+  );
+  const required = Object.entries(shape)
+    .filter(([, field]) => !field.flags.optional && field.flags.defaultValue === undefined)
+    .map(([key]) => key);
+
+  return { type: 'object', properties, required, additionalProperties: false };
+}
+
+/** Serializes a Janux type to standard JSON Schema (for the manifest and MCP tools). */
+export function toJsonSchema(type: JxType): Record<string, unknown> {
+  const base = baseSchema(type);
+
+  if (type.flags.nullable) base.type = [base.type, 'null'].flat();
+  if (type.flags.defaultValue !== undefined) base.default = type.flags.defaultValue;
+  if (type.flags.min !== undefined) base.minimum = type.flags.min;
+  if (type.flags.max !== undefined) base.maximum = type.flags.max;
+  if (type.kind === 'money') base.format = 'money-minor-units';
+
+  return base;
+}

package/src/schema/types.ts

@@ -0,0 +1,65 @@
+export type JxKind =
+  | 'string'
+  | 'int'
+  | 'number'
+  | 'boolean'
+  | 'money'
+  | 'enum'
+  | 'list'
+  | 'object';
+
+export interface JxFlags {
+  optional?: boolean;
+  nullable?: boolean;
+  defaultValue?: unknown;
+  min?: number;
+  max?: number;
+}
+
+export interface JxExtra {
+  values?: readonly string[];
+  item?: JxType;
+  shape?: Record<string, JxType>;
+}
+
+export class JxType {
+  readonly kind: JxKind;
+  readonly flags: JxFlags;
+  readonly values?: readonly string[];
+  readonly item?: JxType;
+  readonly shape?: Record<string, JxType>;
+
+  constructor(kind: JxKind, extra: JxExtra = {}, flags: JxFlags = {}) {
+    this.kind = kind;
+    this.flags = flags;
+    this.values = extra.values;
+    this.item = extra.item;
+    this.shape = extra.shape;
+  }
+
+  private with(patch: JxFlags): JxType {
+    const extra = { values: this.values, item: this.item, shape: this.shape };
+
+    return new JxType(this.kind, extra, { ...this.flags, ...patch });
+  }
+
+  optional(): JxType {
+    return this.with({ optional: true });
+  }
+
+  nullable(): JxType {
+    return this.with({ nullable: true });
+  }
+
+  default(value: unknown): JxType {
+    return this.with({ defaultValue: value });
+  }
+
+  min(value: number): JxType {
+    return this.with({ min: value });
+  }
+
+  max(value: number): JxType {
+    return this.with({ max: value });
+  }
+}

package/src/schema/validate.ts

@@ -0,0 +1,106 @@
+import type { JxType } from './types';
+
+export interface JxError {
+  path: string;
+  message: string;
+}
+
+export interface JxResult {
+  ok: boolean;
+  value: unknown;
+  errors: JxError[];
+}
+
+const PRIMITIVE_CHECKS: Record<string, (v: unknown) => boolean> = {
+  string: (v) => typeof v === 'string',
+  int: (v) => Number.isInteger(v),
+  money: (v) => Number.isInteger(v),
+  number: (v) => typeof v === 'number' && Number.isFinite(v),
+  boolean: (v) => typeof v === 'boolean',
+};
+
+function fail(path: string, message: string): JxResult {
+  return { ok: false, value: undefined, errors: [{ path, message }] };
+}
+
+function pass(value: unknown): JxResult {
+  return { ok: true, value, errors: [] };
+}
+
+function checkBounds(type: JxType, value: unknown, path: string): JxResult {
+  const { min, max } = type.flags;
+  const size = typeof value === 'string' ? value.length : (value as number);
+
+  if (min !== undefined && size < min) return fail(path, `below min ${min}`);
+  if (max !== undefined && size > max) return fail(path, `above max ${max}`);
+
+  return pass(value);
+}
+
+function validatePrimitive(type: JxType, value: unknown, path: string): JxResult {
+  const check = PRIMITIVE_CHECKS[type.kind];
+
+  if (!check!(value)) return fail(path, `expected ${type.kind}`);
+
+  return checkBounds(type, value, path);
+}
+
+function validateEnum(type: JxType, value: unknown, path: string): JxResult {
+  if (!type.values!.includes(value as string)) {
+    return fail(path, `expected one of: ${type.values!.join(', ')}`);
+  }
+
+  return pass(value);
+}
+
+function validateList(type: JxType, value: unknown, path: string): JxResult {
+  if (!Array.isArray(value)) return fail(path, 'expected list');
+
+  const results = value.map((item, i) => validate(type.item!, item, `${path}[${i}]`));
+  const errors = results.flatMap((r) => r.errors);
+
+  if (errors.length > 0) return { ok: false, value: undefined, errors };
+
+  return pass(results.map((r) => r.value));
+}
+
+function validateObject(type: JxType, value: unknown, path: string): JxResult {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return fail(path, 'expected object');
+  }
+
+  const entries = Object.entries(type.shape!).map(([key, fieldType]) => {
+    const fieldPath = path === '' ? key : `${path}.${key}`;
+
+    return [key, validate(fieldType, (value as any)[key], fieldPath)] as const;
+  });
+  const errors = entries.flatMap(([, r]) => r.errors);
+
+  if (errors.length > 0) return { ok: false, value: undefined, errors };
+
+  return pass(Object.fromEntries(entries.map(([key, r]) => [key, r.value])));
+}
+
+function validatePresent(type: JxType, value: unknown, path: string): JxResult {
+  if (type.kind === 'enum') return validateEnum(type, value, path);
+  if (type.kind === 'list') return validateList(type, value, path);
+  if (type.kind === 'object') return validateObject(type, value, path);
+
+  return validatePrimitive(type, value, path);
+}
+
+/** Validates a value against a schema, applying defaults. Unknown object keys are stripped. */
+export function validate(type: JxType, value: unknown, path = ''): JxResult {
+  if (value === undefined) {
+    if (type.flags.defaultValue !== undefined) return pass(type.flags.defaultValue);
+    if (type.flags.optional) return pass(undefined);
+    if (type.flags.nullable) return pass(null);
+
+    return fail(path, 'required');
+  }
+  if (value === null) {
+    return type.flags.nullable ? pass(null) : fail(path, 'not nullable');
+  }
+
+  return validatePresent(type, value, path);
+}