@janux/cli 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@janux/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Janux CLI: dev (Vite), build (client bundle) and start (production server on Bun).",
   "repository": {
     "type": "git",
@@ -20,10 +20,10 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "janux": "0.1.0",
-    "@janux/server": "0.1.0",
-    "@janux/agent": "0.1.0",
-    "@janux/vite": "0.1.0",
+    "janux": "0.2.1",
+    "@janux/server": "0.2.1",
+    "@janux/agent": "0.2.1",
+    "@janux/vite": "0.2.1",
     "vite": "^7.3.0"
   },
   "homepage": "https://github.com/aralroca/Janux#readme",

package/src/args.test.ts

@@ -7,9 +7,27 @@ describe('janux CLI args', () => {
       command: 'dev',
       port: 4000,
       root: '/app',
+      files: [],
+      url: 'http://localhost:3000',
+      startCommand: undefined,
+      json: false,
     });
     expect(parseArgs(['build'], '/app').command).toBe('build');
     expect(parseArgs(['start'], '/app').command).toBe('start');
+    expect(parseArgs(['verify'], '/app').command).toBe('verify');
+  });
+
+  it('parses eval files and flags', () => {
+    const parsed = parseArgs(
+      ['eval', 'evals/a.eval.json', '--url', 'http://localhost:4000', '--start', 'janux start', '--json'],
+      '/app',
+    );
+
+    expect(parsed.command).toBe('eval');
+    expect(parsed.files).toEqual(['evals/a.eval.json']);
+    expect(parsed.url).toBe('http://localhost:4000');
+    expect(parsed.startCommand).toBe('janux start');
+    expect(parsed.json).toBe(true);
   });
 
   it('falls back to help on unknown commands', () => {
@@ -22,3 +40,11 @@ describe('janux CLI args', () => {
     expect(() => parseArgs(['dev', '--port', 'abc'], '/app')).toThrow(/--port/);
   });
 });
+
+describe('tailwind auto-detection', () => {
+  it('returns undefined when @janux/tailwind is not installed', async () => {
+    const { loadTailwindPlugin } = await import('./commands');
+
+    expect(await loadTailwindPlugin('/tmp/definitely-not-a-janux-app')).toBeUndefined();
+  });
+});

package/src/args.ts

@@ -1,10 +1,15 @@
 export interface CliCommand {
-  command: 'dev' | 'build' | 'start' | 'help';
+  command: 'dev' | 'build' | 'start' | 'verify' | 'eval' | 'help';
   port: number;
   root: string;
+  files: string[];
+  url: string;
+  startCommand?: string;
+  json: boolean;
 }
 
-const COMMANDS = new Set(['dev', 'build', 'start', 'help']);
+const COMMANDS = new Set(['dev', 'build', 'start', 'verify', 'eval', 'help']);
+const VALUE_FLAGS = new Set(['--port', '--url', '--start']);
 
 export const HELP_TEXT = `janux — the agent-native fullstack UI framework
 
@@ -12,14 +17,36 @@ Usage:
   janux dev    [--port 3000]   Start the dev server (Vite + HMR)
   janux build                  Bundle client assets for production
   janux start  [--port 3000]   Run the production server (Bun)
+  janux verify                 Check the agent surface (tool contracts)
+  janux eval   [files...]      Run agent-task scenarios (evals/**/*.eval.json)
+               [--url http://localhost:3000] [--start "janux start"] [--json]
 `;
 
+function flagValue(argv: string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+
+function positionals(argv: string[]): string[] {
+  return argv
+    .slice(1)
+    .filter((arg, index, all) => !arg.startsWith('--') && !VALUE_FLAGS.has(all[index - 1] ?? ''));
+}
+
 export function parseArgs(argv: string[], cwd: string): CliCommand {
   const command = COMMANDS.has(argv[0] ?? '') ? (argv[0] as CliCommand['command']) : 'help';
-  const portFlag = argv.indexOf('--port');
-  const port = portFlag >= 0 ? Number(argv[portFlag + 1]) : Number(process.env.PORT ?? 3000);
+  const port = Number(flagValue(argv, '--port') ?? process.env.PORT ?? 3000);
 
   if (Number.isNaN(port)) throw new Error('janux: --port must be a number');
 
-  return { command, port, root: cwd };
+  return {
+    command,
+    port,
+    root: cwd,
+    files: positionals(argv),
+    url: flagValue(argv, '--url') ?? 'http://localhost:3000',
+    startCommand: flagValue(argv, '--start'),
+    json: argv.includes('--json'),
+  };
 }

package/src/commands.ts

@@ -5,9 +5,31 @@ import { defineAgent } from '@janux/agent';
 import { apiFiles, apiModuleName, janux, resolveAppConfig } from '@janux/vite';
 import type { CliCommand } from './args';
 
+/** Zero-config integrations: installing @janux/tailwind IS the configuration. */
+export async function loadTailwindPlugin(root: string): Promise<any | undefined> {
+  try {
+    const mod = await import(Bun.resolveSync('@janux/tailwind', root));
+
+    return mod.default();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Shared vite options: janux plugin + the tailwind postcss pipeline when installed. */
+async function viteOptions(root: string): Promise<Record<string, unknown>> {
+  const tailwind = await loadTailwindPlugin(root);
+
+  return {
+    root,
+    plugins: [janux()],
+    css: tailwind ? { postcss: { plugins: [tailwind] } } : undefined,
+  };
+}
+
 export async function dev({ root, port }: CliCommand): Promise<void> {
   const { createServer } = await import('vite');
-  const server = await createServer({ root, plugins: [janux()], server: { port } });
+  const server = await createServer({ ...(await viteOptions(root)), server: { port } });
 
   await server.listen();
   console.log(`\n  janux dev ready\n  → app:      http://localhost:${port}/`);
@@ -15,24 +37,77 @@ export async function dev({ root, port }: CliCommand): Promise<void> {
   console.log(`  → agent:    http://localhost:${port}/_janux/agent\n`);
 }
 
+function bundleInputs(app: { clientEntry: string; stylesheet?: string }, tailwind: boolean) {
+  const input: Record<string, string> = {};
+
+  if (app.clientEntry) input.client = app.clientEntry;
+  if (tailwind && app.stylesheet) input.styles = app.stylesheet;
+
+  return input;
+}
+
+function cssAsStyles(info: any): string {
+  const name = info.names?.[0] ?? info.name ?? '';
+
+  return name.endsWith('.css') ? 'styles.css' : 'assets/[name]-[hash][extname]';
+}
+
+async function bundleClient(root: string, input: Record<string, string>): Promise<void> {
+  const { build: viteBuild } = await import('vite');
+
+  await viteBuild({
+    ...(await viteOptions(root)),
+    build: {
+      outDir: 'dist/client',
+      rollupOptions: {
+        input,
+        output: {
+          entryFileNames: (chunk: any) => (chunk.name === 'client' ? 'client.js' : '[name].js'),
+          assetFileNames: cssAsStyles,
+        },
+      },
+    },
+  });
+}
+
 export async function build({ root }: CliCommand): Promise<void> {
   const app = resolveAppConfig(root);
+  const tailwind = await loadTailwindPlugin(root);
+  const input = bundleInputs(app, tailwind !== undefined);
 
-  if (app.clientEntry) {
-    const { build: viteBuild } = await import('vite');
+  if (Object.keys(input).length > 0) await bundleClient(root, input);
+  else console.log('janux build: nothing to bundle — fully static app (0 KB JS).');
+  if (tailwind === undefined) copyStylesheet(app.stylesheet, root);
+  copyPublicDir(root);
+  if (app.output === 'static') await prerenderStatic(root);
+}
 
-    await viteBuild({
-      root,
-      plugins: [janux()],
-      build: {
-        outDir: 'dist/client',
-        rollupOptions: { input: app.clientEntry, output: { entryFileNames: 'client.js' } },
-      },
-    });
-  } else {
-    console.log('janux build: no src/client.ts — fully static app, nothing to bundle (0 KB JS).');
-  }
-  copyStylesheet(app.stylesheet, root);
+async function writePage(server: { fetch(req: Request): Promise<Response> }, outDir: string, page: string): Promise<void> {
+  const response = await server.fetch(new Request(`http://localhost${page}`));
+  const dir = join(outDir, page.slice(1));
+
+  mkdirSync(dir, { recursive: true });
+  await Bun.write(join(dir, 'index.html'), await response.text());
+}
+
+/** `output: "static"`: prerenders every concrete page (dynamic routes via `staticParams`) into dist/client. */
+async function prerenderStatic(root: string): Promise<void> {
+  const server = createJanuxServer(await prodServerOptions(root));
+  const pages = await server.listPages();
+  const outDir = join(root, 'dist/client');
+  const concrete = pages.filter((page) => !page.includes('['));
+  const skipped = pages.filter((page) => page.includes('['));
+
+  skipped.forEach((page) => console.log(`janux build: skipped ${page} — dynamic route without staticParams.`));
+  await Promise.all(concrete.map((page) => writePage(server, outDir, page)));
+  await writeLlmsTxt(server, outDir);
+  console.log(`janux build: prerendered ${concrete.length} pages (output: static).`);
+}
+
+async function writeLlmsTxt(server: { fetch(req: Request): Promise<Response> }, outDir: string): Promise<void> {
+  const response = await server.fetch(new Request('http://localhost/llms.txt'));
+
+  if (response.status === 200) await Bun.write(join(outDir, 'llms.txt'), await response.text());
 }
 
 function copyStylesheet(stylesheet: string | undefined, root: string): void {
@@ -43,7 +118,14 @@ function copyStylesheet(stylesheet: string | undefined, root: string): void {
   cpSync(stylesheet, join(outDir, 'styles.css'));
 }
 
-async function prodServerOptions(root: string): Promise<ServerOptions> {
+function copyPublicDir(root: string): void {
+  const publicDir = join(root, 'public');
+
+  if (!existsSync(publicDir)) return;
+  cpSync(publicDir, join(root, 'dist/client'), { recursive: true });
+}
+
+export async function prodServerOptions(root: string): Promise<ServerOptions> {
   const app = resolveAppConfig(root);
   const apiModules = Object.fromEntries(
     await Promise.all(
@@ -61,6 +143,7 @@ async function prodServerOptions(root: string): Promise<ServerOptions> {
     runtimeUrl: existsSync(join(root, 'dist/client/client.js')) ? '/client.js' : undefined,
     stylesheets: app.stylesheet ? ['/styles.css'] : [],
     title: app.title,
+    llmsTxt: app.llmsTxt,
   };
 }
 

package/src/eval-runner.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'bun:test';
+import { deepSubset, resolveRefs, runScenario, type StepOutcome } from './eval-runner';
+
+const outcomes: StepOutcome[] = [
+  { status: 200, ok: true, result: { status: 'proposal', id: 'prop_1', nested: { total: 42 } } },
+];
+
+describe('resolveRefs', () => {
+  it('resolves $steps references anywhere in a value', () => {
+    const input = { id: '$steps[0].result.id', deep: ['$steps[0].result.nested.total'], plain: 'x' };
+
+    expect(resolveRefs(input, outcomes)).toEqual({ id: 'prop_1', deep: [42], plain: 'x' });
+  });
+
+  it('throws on unresolvable references', () => {
+    expect(() => resolveRefs('$steps[0].result.missing', outcomes)).toThrow('unresolvable');
+  });
+});
+
+describe('deepSubset', () => {
+  it('matches structural subsets and rejects mismatches', () => {
+    expect(deepSubset({ a: { b: 1 } }, { a: { b: 1, c: 2 }, extra: true })).toBe(true);
+    expect(deepSubset([{ id: 'p1' }], [{ id: 'p1', name: 'x' }, { id: 'p2' }])).toBe(true);
+    expect(deepSubset({ a: 1 }, { a: 2 })).toBe(false);
+  });
+});
+
+function fakeServer(): typeof fetch {
+  const respond = (body: unknown, status = 200) =>
+    new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+
+  return (async (url: any, init: any) => {
+    const body = JSON.parse(init.body);
+
+    if (String(url).endsWith('/_janux/api/shop.pay')) {
+      expect(init.headers['x-janux-origin']).toBe('agent');
+
+      return respond({ ok: true, result: { status: 'proposal', id: 'prop_9', tool: 'shop.pay', input: body } });
+    }
+    if (String(url).endsWith('/_janux/approve')) {
+      return body.id === 'prop_9'
+        ? respond({ ok: true, result: { charged: 5999 } })
+        : respond({ ok: false, error: 'unknown proposal' }, 404);
+    }
+
+    return respond({ ok: false, error: 'unknown api' }, 404);
+  }) as typeof fetch;
+}
+
+describe('runScenario', () => {
+  it('carries proposal ids into approve steps and passes', async () => {
+    const report = await runScenario(
+      {
+        name: 'pay flow',
+        steps: [
+          { tool: 'api.shop.pay', input: { total: 5999 }, expect: { result: { status: 'proposal' } } },
+          { approve: '$steps[0].result.id', expect: { result: { charged: 5999 } } },
+        ],
+      },
+      'http://test',
+      fakeServer(),
+    );
+
+    expect(report.pass).toBe(true);
+    expect(report.steps.map((step) => step.pass)).toEqual([true, true]);
+  });
+
+  it('fails on unmet expectations with a detail', async () => {
+    const report = await runScenario(
+      { name: 'bad', steps: [{ tool: 'shop.pay', expect: { result: { status: 'done' } } }] },
+      'http://test',
+      fakeServer(),
+    );
+
+    expect(report.pass).toBe(false);
+    expect(report.steps[0]?.detail).toContain('result mismatch');
+  });
+
+  it('fails steps with unresolvable references without aborting the scenario', async () => {
+    const report = await runScenario(
+      { name: 'refs', steps: [{ approve: '$steps[5].result.id' }, { tool: 'shop.pay', expect: { result: { status: 'proposal' } } }] },
+      'http://test',
+      fakeServer(),
+    );
+
+    expect(report.steps[0]?.pass).toBe(false);
+    expect(report.steps[1]?.pass).toBe(true);
+  });
+});

package/src/eval-runner.ts

@@ -0,0 +1,139 @@
+export interface EvalExpect {
+  ok?: boolean;
+  status?: number;
+  error?: string;
+  result?: unknown;
+}
+
+export interface EvalStep {
+  tool?: string;
+  approve?: string;
+  input?: unknown;
+  expect?: EvalExpect;
+}
+
+export interface EvalScenario {
+  name: string;
+  url?: string;
+  steps: EvalStep[];
+}
+
+export interface StepOutcome {
+  status: number;
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+}
+
+export interface StepReport {
+  label: string;
+  pass: boolean;
+  detail?: string;
+  outcome: StepOutcome;
+}
+
+export interface ScenarioReport {
+  name: string;
+  pass: boolean;
+  steps: StepReport[];
+}
+
+const REF_PATTERN = /^\$steps\[(\d+)\]\.(.+)$/;
+
+function resolveRef(value: string, outcomes: StepOutcome[]): unknown {
+  const match = REF_PATTERN.exec(value);
+
+  if (!match) return value;
+  const outcome = outcomes[Number(match[1])];
+  const resolved = match[2]!.split('.').reduce<unknown>((acc, key) => (acc as any)?.[key], outcome);
+
+  if (resolved === undefined) throw new Error(`unresolvable reference "${value}"`);
+
+  return resolved;
+}
+
+/** Replaces `$steps[i].<dot.path>` strings anywhere in a value with earlier step outcomes. */
+export function resolveRefs(value: unknown, outcomes: StepOutcome[]): unknown {
+  if (typeof value === 'string') return resolveRef(value, outcomes);
+  if (Array.isArray(value)) return value.map((item) => resolveRefs(item, outcomes));
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, resolveRefs(item, outcomes)]));
+  }
+
+  return value;
+}
+
+/** Structural subset match: every expected key/index must match; extra actual data is fine. */
+export function deepSubset(expected: unknown, actual: unknown): boolean {
+  if (expected === null || typeof expected !== 'object') return Object.is(expected, actual);
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) && expected.every((item, index) => deepSubset(item, actual[index]));
+  }
+
+  return (
+    actual !== null &&
+    typeof actual === 'object' &&
+    Object.entries(expected).every(([key, item]) => deepSubset(item, (actual as any)[key]))
+  );
+}
+
+function checkExpect(expect: EvalExpect | undefined, outcome: StepOutcome): string | undefined {
+  const rules = expect ?? { ok: true };
+
+  if (rules.ok !== undefined && outcome.ok !== rules.ok) return `expected ok ${rules.ok}, got ${outcome.ok} (${outcome.error ?? ''})`;
+  if (rules.status !== undefined && outcome.status !== rules.status) return `expected status ${rules.status}, got ${outcome.status}`;
+  if (rules.error !== undefined && !String(outcome.error ?? '').includes(rules.error)) return `expected error containing "${rules.error}", got "${outcome.error}"`;
+  if (rules.result !== undefined && !deepSubset(rules.result, outcome.result)) return `result mismatch, got ${JSON.stringify(outcome.result)}`;
+
+  return undefined;
+}
+
+function stepRequest(step: EvalStep, outcomes: StepOutcome[]): { path: string; body: unknown; headers: Record<string, string> } {
+  if (step.approve) {
+    return { path: '/_janux/approve', body: { id: resolveRefs(step.approve, outcomes) }, headers: {} };
+  }
+  if (!step.tool) throw new Error('step needs "tool" or "approve"');
+
+  return {
+    path: `/_janux/api/${step.tool.replace(/^api\./, '')}`,
+    body: resolveRefs(step.input ?? {}, outcomes),
+    headers: { 'x-janux-origin': 'agent' },
+  };
+}
+
+async function performStep(step: EvalStep, outcomes: StepOutcome[], baseUrl: string, fetchImpl: typeof fetch): Promise<StepOutcome> {
+  const { path, body, headers } = stepRequest(step, outcomes);
+  const res = await fetchImpl(`${baseUrl}${path}`, {
+    method: 'POST',
+    body: JSON.stringify(body),
+    headers: { 'content-type': 'application/json', ...headers },
+  });
+  const envelope = (await res.json().catch(() => ({}))) as { ok?: boolean; result?: unknown; error?: string };
+
+  return { status: res.status, ok: envelope.ok === true, result: envelope.result, error: envelope.error };
+}
+
+/** Runs one scenario's steps in order against a live app's agent surface. */
+export async function runScenario(scenario: EvalScenario, baseUrl: string, fetchImpl: typeof fetch = fetch): Promise<ScenarioReport> {
+  const outcomes: StepOutcome[] = [];
+  const steps: StepReport[] = [];
+
+  // Sequential by design: later steps reference earlier outcomes ($steps[i]).
+  for (const [index, step] of scenario.steps.entries()) {
+    const label = step.approve ? `approve ${step.approve}` : (step.tool ?? `step ${index}`);
+    let report: StepReport;
+
+    try {
+      const outcome = await performStep(step, outcomes, baseUrl, fetchImpl);
+      const detail = checkExpect(step.expect, outcome);
+
+      report = { label, pass: !detail, detail, outcome };
+    } catch (error) {
+      report = { label, pass: false, detail: String(error), outcome: { status: 0, ok: false, error: String(error) } };
+    }
+    outcomes.push(report.outcome);
+    steps.push(report);
+  }
+
+  return { name: scenario.name, pass: steps.every((step) => step.pass), steps };
+}

package/src/eval.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { runScenario, type EvalScenario, type ScenarioReport } from './eval-runner';
+import type { CliCommand } from './args';
+
+const START_TIMEOUT_MS = 30_000;
+
+function scenarioFiles({ files, root }: CliCommand): string[] {
+  if (files.length > 0) return files.map((file) => resolve(root, file));
+
+  return [...new Bun.Glob('evals/**/*.eval.json').scanSync(root)].map((file) => resolve(root, file));
+}
+
+async function waitForServer(url: string): Promise<void> {
+  const deadline = Date.now() + START_TIMEOUT_MS;
+
+  while (Date.now() < deadline) {
+    const responded = await fetch(url).then(() => true, () => false);
+
+    if (responded) return;
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, 500));
+  }
+  throw new Error(`janux eval: server at ${url} did not respond within ${START_TIMEOUT_MS / 1000}s`);
+}
+
+function stopApp(proc: ChildProcess): void {
+  if (proc.pid) {
+    try {
+      process.kill(-proc.pid, 'SIGTERM');
+    } catch {
+      proc.kill('SIGTERM');
+    }
+  }
+}
+
+function reportHuman(results: ScenarioReport[]): void {
+  results.forEach((result) => {
+    console.log(`\n${result.pass ? '✓' : '✗'} ${result.name}`);
+    result.steps.forEach((step) =>
+      console.log(`  ${step.pass ? '✓' : '✗'} ${step.label}${step.detail ? ` — ${step.detail}` : ''}`),
+    );
+  });
+}
+
+async function runFiles(files: string[], baseUrl: string): Promise<ScenarioReport[]> {
+  const results: ScenarioReport[] = [];
+
+  // Sequential: scenarios share one live app and may mutate its state.
+  for (const file of files) {
+    const scenario = JSON.parse(readFileSync(file, 'utf8')) as EvalScenario;
+
+    results.push(await runScenario(scenario, scenario.url ?? baseUrl));
+  }
+
+  return results;
+}
+
+export async function evalCommand(parsed: CliCommand): Promise<void> {
+  const files = scenarioFiles(parsed);
+
+  if (files.length === 0) throw new Error('janux eval: no scenario files found (evals/**/*.eval.json)');
+  const proc = parsed.startCommand
+    ? spawn(parsed.startCommand, { shell: true, detached: true, stdio: 'inherit', cwd: parsed.root })
+    : undefined;
+
+  try {
+    if (proc) await waitForServer(parsed.url);
+    const results = await runFiles(files, parsed.url);
+
+    if (parsed.json) console.log(JSON.stringify(results, null, 2));
+    else reportHuman(results);
+    if (results.some((result) => !result.pass)) process.exitCode = 1;
+  } finally {
+    if (proc) stopApp(proc);
+  }
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 import { HELP_TEXT, parseArgs } from './args';
 import { build, dev, start } from './commands';
+import { verify } from './verify';
+import { evalCommand } from './eval';
 
 export { parseArgs, HELP_TEXT } from './args';
 
@@ -9,5 +11,7 @@ export async function runCli(argv: string[]): Promise<void> {
   if (parsed.command === 'dev') return dev(parsed);
   if (parsed.command === 'build') return build(parsed);
   if (parsed.command === 'start') return start(parsed);
+  if (parsed.command === 'verify') return verify(parsed);
+  if (parsed.command === 'eval') return evalCommand(parsed);
   console.log(HELP_TEXT);
 }

package/src/verify.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'bun:test';
+import { component, intent, jsx, schema, str } from 'janux';
+import { api, createJanuxServer } from '@janux/server';
+import { auditManifest, collectFindings } from './verify';
+
+const apis = {
+  described: api({
+    description: 'Search things',
+    input: schema({ q: str() }),
+    run: ({ input }) => [input.q],
+  }),
+  undescribed: api({ guard: 'confirm', run: () => 'paid' }),
+  hidden: api({ guard: 'forbidden', run: () => 'secret' }),
+};
+
+const bareCart = component({
+  name: 'bare-cart',
+  state: schema({ items: str() }),
+  intents: { add: intent({ run: () => undefined }) },
+  view: () => jsx('p', { children: 'cart' }),
+});
+
+const server = createJanuxServer({
+  routes: {
+    '/': () => jsx('main', {}),
+    '/shop': () => jsx('div', { children: jsx(bareCart as any, {}) }),
+    '/boom': () => {
+      throw new Error('render exploded');
+    },
+  },
+  apis: { shop: apis },
+});
+
+const manifestFor = (path: string) => server.manifestFor(path, {});
+
+describe('auditManifest', () => {
+  it('flags agent-reachable tools without description', () => {
+    const findings = auditManifest({
+      tools: [
+        { name: 'a.ok', description: 'fine', guard: 'auto' },
+        { name: 'a.bad', guard: 'confirm' },
+      ],
+    });
+
+    expect(findings).toEqual([
+      { level: 'error', tool: 'a.bad', message: 'missing description (agent-reachable, guard "confirm")' },
+    ]);
+  });
+});
+
+describe('collectFindings', () => {
+  it('errors on undescribed api tools and intents, once across routes', async () => {
+    const findings = await collectFindings(['/', '/shop'], manifestFor);
+    const tools = findings.map((finding) => finding.tool);
+
+    expect(tools).toContain('api.shop.undescribed');
+    expect(tools).toContain('bare-cart.add');
+    expect(tools.filter((tool) => tool === 'api.shop.undescribed')).toHaveLength(1);
+  });
+
+  it('never flags forbidden tools (not agent-reachable)', async () => {
+    const findings = await collectFindings(['/'], manifestFor);
+
+    expect(findings.map((finding) => finding.tool)).not.toContain('api.shop.hidden');
+  });
+
+  it('warns when a route fails to render', async () => {
+    const findings = await collectFindings(['/boom'], manifestFor);
+
+    expect(findings[0]?.level).toBe('warn');
+    expect(findings[0]?.message).toContain('/boom');
+    expect(findings[0]?.message).toContain('render exploded');
+  });
+});

package/src/verify.ts

@@ -0,0 +1,85 @@
+import { createFsRouter, createJanuxServer } from '@janux/server';
+import type { ManifestTool } from 'janux/manifest';
+import { prodServerOptions } from './commands';
+import type { CliCommand } from './args';
+
+export interface VerifyFinding {
+  level: 'error' | 'warn';
+  tool?: string;
+  message: string;
+}
+
+interface ManifestLike {
+  tools: ManifestTool[];
+}
+
+/** Contract checks over one route's manifest: every agent-reachable tool needs a description. */
+export function auditManifest(manifest: ManifestLike): VerifyFinding[] {
+  return manifest.tools
+    .filter((tool) => !tool.description)
+    .map((tool) => ({
+      level: 'error' as const,
+      tool: tool.name,
+      message: `missing description (agent-reachable, guard "${tool.guard}")`,
+    }));
+}
+
+function dedupeFindings(findings: VerifyFinding[]): VerifyFinding[] {
+  const seen = new Set<string>();
+
+  return findings.filter((finding) => {
+    const key = finding.tool ?? finding.message;
+
+    if (seen.has(key)) return false;
+    seen.add(key);
+
+    return true;
+  });
+}
+
+/** Renders every route's manifest and aggregates findings (routes that fail to render are warnings). */
+export async function collectFindings(
+  patterns: string[],
+  manifestFor: (path: string) => Promise<unknown>,
+): Promise<VerifyFinding[]> {
+  const perRoute = await Promise.all(
+    patterns.map(async (pattern) => {
+      try {
+        return auditManifest((await manifestFor(pattern)) as ManifestLike);
+      } catch (error) {
+        return [
+          {
+            level: 'warn' as const,
+            message: `route "${pattern}" failed to render — its agent surface was not verified (${error})`,
+          },
+        ];
+      }
+    }),
+  );
+
+  return dedupeFindings(perRoute.flat());
+}
+
+function report(findings: VerifyFinding[]): void {
+  const errors = findings.filter((finding) => finding.level === 'error').length;
+
+  if (findings.length === 0) {
+    console.log('janux verify: agent surface OK — every reachable tool has a description.');
+
+    return;
+  }
+  findings.forEach((finding) =>
+    console.log(`  ${finding.level.toUpperCase().padEnd(5)} ${finding.tool ? `${finding.tool} — ` : ''}${finding.message}`),
+  );
+  console.log(`\njanux verify: ${errors} error(s), ${findings.length - errors} warning(s).`);
+}
+
+export async function verify({ root }: CliCommand): Promise<void> {
+  const options = await prodServerOptions(root);
+  const server = createJanuxServer(options);
+  const patterns = createFsRouter(options.routesDir!).routes.map((route) => route.pattern);
+  const findings = await collectFindings(patterns, (path) => server.manifestFor(path, {}));
+
+  report(findings);
+  if (findings.some((finding) => finding.level === 'error')) process.exitCode = 1;
+}