pi-revit 0.5.0 → 0.5.2

package/scripts/check-tool-documentation.mjs

@@ -1,287 +0,0 @@
-import assert from 'node:assert/strict';
-import { existsSync } from 'node:fs';
-import { access, readFile, readdir } from 'node:fs/promises';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import {
-  CONTRACT_END, CONTRACT_START, createLoader, evaluateCorpus, extractBridgeDescriptors, manifestPath, manualRoot, registerExtension,
-  resolvePiDependencies, revitApiXmlPaths, root, skillRoot, snapshotPath,
-} from './lib/platform.mjs';
-import { buildArtifacts } from './generate-contracts.mjs';
-
-// Offline platform gates: no model execution, real bridge connection or package
-// installation. Source metadata, generated artifacts, schemas, guidance structure and
-// prompt size are checked; Revit bodies and agent behavior need their own tests.
-// Budgets change deliberately, never by accident: raise them only with a reviewed reason
-// in the change log. The startup total covers the platform section plus the snippets and
-// guidelines of tools active at session start; it must not grow with the tool count.
-const PROMPT_BUDGET = { startupTotal: 7000, perToolGuidelines: 1200 };
-const problems = [];
-const warnings = [];
-const fail = message => problems.push(message);
-
-const piRequire = resolvePiDependencies();
-const loader = createLoader(piRequire);
-const { Check, Errors } = await import(pathToFileURL(piRequire.resolve('typebox/value')).href);
-assert.equal(Check({ type: 'integer', minimum: 1 }, 0), false, 'schema validator must enforce numeric constraints');
-assert.equal(Check({ type: 'object', required: ['id'], properties: { id: { type: 'integer' } } }, {}), false,
-  'schema validator must enforce required properties');
-
-// 1. Generated artifacts are current: code is the single owner of contracts.
-const { files: generated } = await buildArtifacts();
-for (const [file, content] of generated)
-  if (!existsSync(file) || await readFile(file, 'utf8') !== content) fail(`${path.relative(root, file)}: generated artifact is stale; run npm run generate:contracts`);
-
-const packageInfo = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
-const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
-const snapshot = JSON.parse(await readFile(snapshotPath, 'utf8'));
-const descriptors = await extractBridgeDescriptors();
-const bridgeNames = new Set(descriptors.map(tool => tool.name));
-assert.ok(descriptors.length > 0, 'real registry must expose bridge descriptors');
-assert.equal(bridgeNames.size, descriptors.length, 'bridge tool names must be unique');
-
-// 2. Documentation manifest v2 structure.
-assert.equal(manifest.schema_version, 2, 'unrecognized documentation manifest schema');
-assert.ok(typeof manifest.documentation_revision === 'string' && manifest.documentation_revision.trim(), 'documentation revision is required');
-const groupIds = new Set(manifest.groups.map(group => group.id));
-const manifestNames = new Set(manifest.tools.map(tool => tool.name));
-assert.equal(manifestNames.size, manifest.tools.length, 'manifest tool names must be unique');
-for (const tool of manifest.tools) {
-  assert.match(tool.name, /^[a-z][a-z0-9_]*$/, 'tool names must be safe filenames');
-  assert.ok(['bridge', 'native'].includes(tool.source), `${tool.name}: source must be bridge or native`);
-  assert.ok(typeof tool.summary === 'string' && tool.summary.trim(), `${tool.name}: summary is required`);
-  if (!groupIds.has(tool.group)) fail(`${tool.name}: unknown manifest group ${tool.group}`);
-}
-assert.deepEqual(manifest.tools.filter(tool => tool.source === 'bridge').map(tool => tool.name).sort(), [...bridgeNames].sort(),
-  'manifest bridge inventory must equal the real C# registry');
-const guidanceNames = new Set();
-for (const guide of manifest.guidance) {
-  if (guidanceNames.has(guide.name)) fail(`guidance ${guide.name}: duplicate name`);
-  guidanceNames.add(guide.name);
-  if (!['workflow', 'reference', 'skill'].includes(guide.kind)) fail(`guidance ${guide.name}: kind must be workflow, reference or skill`);
-  if (!existsSync(path.join(skillRoot, guide.path))) fail(`guidance ${guide.name}: missing ${guide.path}`);
-  if (!guide.summary?.trim() || !(guide.keywords?.length >= 3)) fail(`guidance ${guide.name}: needs a summary and at least 3 keywords`);
-}
-
-// 3. Real registration against the extracted bridge catalogue.
-const fixture = await registerExtension(loader, descriptors, packageInfo.version);
-const { publicBridgeSchema } = await loader.import(path.join(root, 'extensions', 'pi-revit', 'tool-schema.ts'));
-const { ALTERNATIVE_KINDS, VERIFICATION_KINDS, apiLookupQuery } = await loader.import(path.join(root, 'extensions', 'pi-revit', 'contracts.ts'));
-const registered = fixture.registered;
-let promptReport;
-try {
-  assert.ok(fixture.routes.includes('/tools'), 'connector must register real extracted bridge schemas');
-  assert.deepEqual([...registered.keys()].sort(), [...manifestNames].sort(), 'manifest must cover every registered public tool');
-  assert.deepEqual(manifest.tools.filter(tool => tool.source === 'native').map(tool => tool.name).sort(),
-    [...registered.keys()].filter(name => !bridgeNames.has(name)).sort(), 'native inventory must match actual extension registrations');
-  for (const descriptor of descriptors)
-    assert.deepEqual(JSON.parse(JSON.stringify(registered.get(descriptor.name).parameters)), publicBridgeSchema(descriptor.parameters),
-      `${descriptor.name}: registered parameters must include the actual extension schema overlay`);
-
-  // 8 (measured here while registered). Prompt budget: the startup contribution must not grow with tool count.
-  await fixture.events.get('session_start')?.({}, { ui: { notify() {} } });
-  const options = { sections: {}, selectedTools: fixture.activeTools() };
-  await fixture.events.get('before_agent_start')?.({ systemPromptOptions: options }, {});
-  const section = options.sections.pi_revit ?? '';
-  const perTool = fixture.activeTools().map(name => ({ name, snippet: registered.get(name)?.promptSnippet ?? '', guidelines: (registered.get(name)?.promptGuidelines ?? []).join('\n') }));
-  const toolChars = perTool.reduce((sum, tool) => sum + tool.snippet.length + tool.guidelines.length, 0);
-  promptReport = { sectionChars: section.length, toolChars, activeTools: perTool.length, total: section.length + toolChars,
-    largestGuidelines: perTool.map(t => [t.name, t.guidelines.length]).sort((a, b) => b[1] - a[1])[0] };
-  if (!section.includes('PI-Revit protocol')) fail('platform section was not injected by before_agent_start');
-  if (/For \w+, read .*\.md when detailed usage/.test(perTool.map(t => t.guidelines).join('\n'))) fail('per-tool manual pointer lines must not return; the platform section holds one pointer');
-  for (const tool of perTool) if (tool.guidelines.length > PROMPT_BUDGET.perToolGuidelines) fail(`${tool.name}: ${tool.guidelines.length} guideline characters exceed the per-tool budget of ${PROMPT_BUDGET.perToolGuidelines}`);
-  if (promptReport.total > PROMPT_BUDGET.startupTotal) fail(`PI-Revit startup prompt contribution ${promptReport.total} characters exceeds the budget of ${PROMPT_BUDGET.startupTotal}`);
-} finally { await fixture.restore(); }
-
-// 4. Contract v2 validity for every tool, including limit references.
-const publicNames = new Set([...registered.keys(), 'read']);
-const apiXml = await Promise.all(revitApiXmlPaths().map(file => readFile(file, 'utf8')));
-if (!apiXml.length) warnings.push('RevitAPI.xml not found; API references in declared limits were not verified (set REVIT_API_PATH).');
-const apiMemberExists = member => apiXml.some(xml => new RegExp(`name="[TMPFE]:Autodesk\\.Revit\\.(?:[A-Za-z0-9]+\\.)*${member.replace(/\./g, '\\.')}(?:["(])`).test(xml));
-for (const tool of snapshot.tools) {
-  if (!(tool.keywords?.length >= 3)) fail(`${tool.name}: declare at least 3 discovery keywords`);
-  if ((tool.write || tool.effects?.length) && !VERIFICATION_KINDS.includes(tool.verification))
-    fail(`${tool.name}: a tool that can write or has effects must declare verification (${VERIFICATION_KINDS.join(', ')})`);
-  if (tool.verification !== null && !VERIFICATION_KINDS.includes(tool.verification)) fail(`${tool.name}: unknown verification ${tool.verification}`);
-  if (!tool.limits.length) fail(`${tool.name}: declare at least one limit with its alternative`);
-  for (const limit of tool.limits) {
-    if (!limit.what?.trim() || !ALTERNATIVE_KINDS.includes(limit.alternative?.kind) || !limit.alternative.ref?.trim())
-      { fail(`${tool.name}: every limit needs what, a known alternative kind and a reference`); continue; }
-    const ref = limit.alternative.ref;
-    if (limit.alternative.kind === 'tool') {
-      const named = [...ref.matchAll(/\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b|\bread\b/g)].map(m => m[0]).filter(name => !['host_bounds', 'include_instance_count', 'count_only', 'next_offset'].includes(name));
-      if (!named.length) fail(`${tool.name}: tool alternative "${ref}" names no public tool`);
-      for (const name of named) if (!publicNames.has(name)) fail(`${tool.name}: tool alternative names unknown tool ${name}`);
-    }
-    // Every name in the generated one-call lookup must resolve, so the lookup never sends the agent searching.
-    if (limit.alternative.kind === 'api' && apiXml.length)
-      for (const member of (apiLookupQuery(ref) ?? '').split('; ').filter(Boolean))
-        if (!apiMemberExists(member)) fail(`${tool.name}: API alternative ${member} was not found in the installed RevitAPI.xml`);
-  }
-  // Required inputs must not be described as optional anywhere in their schema text.
-  for (const name of tool.parameters?.required ?? [])
-    if (/\boptional\b/i.test(tool.parameters.properties?.[name]?.description ?? '')) fail(`${tool.name}.${name}: a required input's description says "optional"`);
-}
-
-// 5. Manuals: one per tool, generated block present, examples valid, limitation language declared.
-const manualFiles = (await readdir(manualRoot)).filter(file => file.endsWith('.md')).sort();
-assert.deepEqual(manualFiles, [...manifestNames].map(name => `${name}.md`).sort(), 'one manual per public tool; no orphan manuals');
-const snapshotByName = new Map(snapshot.tools.map(tool => [tool.name, tool]));
-let exampleCount = 0;
-for (const tool of manifest.tools) {
-  const file = path.join(manualRoot, `${tool.name}.md`);
-  const markdown = await readFile(file, 'utf8');
-  if (!markdown.includes(CONTRACT_START) || !markdown.includes(CONTRACT_END)) fail(`${tool.name}: manual lacks its generated contract block`);
-  const handWritten = markdown.slice(0, markdown.indexOf(CONTRACT_START)) + markdown.slice(markdown.indexOf(CONTRACT_END) + CONTRACT_END.length);
-  if (/outside this tool|\bunsupported\b|not supported/i.test(handWritten) && !snapshotByName.get(tool.name)?.limits.length)
-    fail(`${tool.name}: the manual states a limitation but the tool declares no limits with alternatives`);
-  const examples = [...markdown.matchAll(/^```json[ \t]*\r?\n([\s\S]*?)^```[ \t]*\r?$/gm)];
-  if (examples.length === 0) fail(`${tool.name}: missing JSON input example`);
-  const schema = registered.get(tool.name).parameters;
-  for (const match of examples) {
-    const label = `${path.relative(root, file)}:${markdown.slice(0, match.index).split('\n').length + 1}`;
-    try {
-      const input = JSON.parse(match[1]);
-      assert.ok(input !== null && typeof input === 'object' && !Array.isArray(input), 'example must be an input argument object');
-      if (!Check(schema, input)) throw new Error(JSON.stringify([...Errors(schema, input)]));
-      assertDocumentedKeys(schema, input, label);
-      // Negative controls exercise the actual composed schemas rather than a copied test schema.
-      for (const key of schema.required ?? []) {
-        const missingRequired = { ...input };
-        delete missingRequired[key];
-        assert.equal(Check(schema, missingRequired), false, `${tool.name}: required ${key} was not enforced`);
-      }
-      if (schema.properties?._operation_id) assert.equal(Check(schema, { ...input, _operation_id: 42 }), false, `${tool.name}: retry ID must remain a string`);
-      exampleCount++;
-    } catch (error) { fail(`${label}: ${error.message}`); }
-  }
-}
-
-// 6. Invariant register: every rule has an owner and an enforcement, and guidance tags resolve.
-const register = JSON.parse(await readFile(path.join(root, 'docs', 'invariants.json'), 'utf8'));
-const invariants = new Map(register.invariants.map(item => [item.id, item]));
-const guidanceFiles = [...await markdownUnder(path.join(root, 'skills')), ...await markdownUnder(path.join(root, 'docs')),
-  ...['AGENTS.md', 'README.md', 'workspace/AGENTS.md'].map(file => path.join(root, file))];
-const tagged = new Set();
-const testSources = (await Promise.all((await filesUnder(path.join(root, 'tests'))).filter(file => /\.(mjs|cjs|cs)$/.test(file)).map(file => readFile(file, 'utf8')))).join('\n')
-  + await readFile(new URL(import.meta.url), 'utf8');
-for (const file of guidanceFiles) {
-  const text = await readFile(file, 'utf8');
-  for (const match of text.matchAll(/<!-- inv:([a-z0-9-]+) -->/g)) {
-    tagged.add(match[1]);
-    if (!invariants.has(match[1])) fail(`${path.relative(root, file)}: tag inv:${match[1]} is not in docs/invariants.json`);
-  }
-}
-const coreRules = ['skills/pi-revit/SKILL.md', 'skills/pi-revit/references/execution-rules.md', 'skills/pi-revit/references/operation-recovery.md',
-  'skills/pi-revit/references/visual-verification.md', 'workspace/AGENTS.md'];
-for (const relative of coreRules)
-  for (const [index, line] of (await readFile(path.join(root, relative), 'utf8')).split(/\r?\n/).entries())
-    if (/\b(never|must not)\b/i.test(line) && !/<!-- inv:[a-z0-9-]+ -->/.test(line)) fail(`${relative}:${index + 1}: a never/must-not rule needs an <!-- inv:<id> --> tag and a register entry`);
-for (const item of register.invariants) {
-  if (!['safety', 'correctness', 'guidance'].includes(item.severity)) fail(`inv:${item.id}: unknown severity`);
-  if (!tagged.has(item.id)) fail(`inv:${item.id}: no guidance sentence carries this tag`);
-  if (item.enforcement === 'code') {
-    if (!item.test || !testSources.includes(item.test)) fail(`inv:${item.id}: enforcement=code needs an existing test titled "${item.test}"`);
-    for (const location of item.location ?? []) if (!existsSync(path.join(root, location))) fail(`inv:${item.id}: missing location ${location}`);
-  } else if (item.enforcement === 'advisory') {
-    if (!item.reason) fail(`inv:${item.id}: advisory rules must state why code cannot enforce them`);
-    if (item.severity === 'safety' && !item.eval_scenario) fail(`inv:${item.id}: an advisory safety rule must name the agent-eval scenario that measures it`);
-  } else fail(`inv:${item.id}: enforcement must be code or advisory`);
-}
-const scenarioFile = path.join(root, 'tests', 'agent-eval', 'scenarios.json');
-const scenarioIds = existsSync(scenarioFile) ? new Set(JSON.parse(await readFile(scenarioFile, 'utf8')).scenarios.map(s => s.id)) : new Set();
-for (const item of register.invariants) if (item.eval_scenario && !scenarioIds.has(item.eval_scenario)) fail(`inv:${item.id}: eval scenario ${item.eval_scenario} is not defined in tests/agent-eval/scenarios.json`);
-
-// Architecture gates over every bridge source file, present and future. Shared primitives
-// own cross-cutting policy; a new tool cannot reintroduce a private variant.
-for (const file of (await readdir(path.join(root, 'src', 'Revit', 'Tools'))).filter(name => name.endsWith('.cs'))) {
-  const source = (await readFile(path.join(root, 'src', 'Revit', 'Tools', file), 'utf8')).replace(/\/\/.*$/gm, '').replace(/"(?:[^"\\]|\\.)*"/g, '""');
-  // inv:no-tool-saves-model
-  if (/\.\s*(Save|SaveAs|Close|SynchronizeWithCentral)\s*\(/.test(source)) fail(`architecture: no bridge tool saves, closes or synchronizes a document (${file})`);
-  // inv:parameter-ambiguity: LookupParameter returns an arbitrary one of several same-named parameters.
-  if (file !== 'ParameterResolver.cs' && /\b(LookupParameter|GetParameters)\s*\(/.test(source))
-    fail(`architecture: ${file} resolves parameters by name directly; use ParameterResolver (one ambiguity policy for every tool)`);
-  // inv:special-objects-flagged: sheet-owned schedule instances include the titleblock's revision schedule.
-  if (file !== 'ElementTraits.cs' && /\bScheduleSheetInstance\b/.test(source) && !/\bElementTraits\./.test(source))
-    fail(`architecture: ${file} handles ScheduleSheetInstance without ElementTraits classification`);
-  // inv:derived-state-reported: an object made from an existing one carries its hidden content, overrides and values.
-  if (file !== 'InheritedState.cs' && /\.\s*Duplicate\s*\(|\bCopyElements?\s*\(|\bMirrorElements\s*\(|\.\s*ChangeTypeId\s*\(/.test(source) && !/\bInheritedState\./.test(source))
-    fail(`architecture: a tool that duplicates, copies or retypes reports inherited state; ${file} creates from an existing object without InheritedState`);
-  // inv:existing-objects-not-reused: names and sheet numbers go through the one collision check.
-  if (file !== 'ElementNames.cs' && /\.\s*(Name|SheetNumber)\s*=(?!=)|\.\s*(NewType|RenameCurrentType)\s*\(/.test(source))
-    fail(`architecture: names are assigned through ElementNames; ${file} assigns a Name, SheetNumber or family type name directly`);
-  // inv:document-kind-declared: every tool states where it works, so the dispatcher can refuse the rest.
-  if (/:\s*ITool\b/.test(source) && !/\bDocumentKinds\s*=>/.test(source))
-    fail(`architecture: every bridge tool declares the document kinds it supports; ${file} has no DocumentKinds`);
-}
-// inv:model-changes-reported: the dispatcher, not each tool, attaches model_changes to every model-changing call.
-{
-  const server = await readFile(path.join(root, 'src', 'Revit', 'BridgeServer.cs'), 'utf8');
-  if (!/ModelChangeRecorder\.For\(\s*tool\b/.test(server) || !/\.Attach\(/.test(server))
-    fail('architecture: the bridge dispatcher records model changes for every tool call (ModelChangeRecorder.For(tool, ...) and Attach)');
-}
-
-// 7. Discovery corpus: English task phrasings (the model translates other languages).
-// Every public tool needs coverage; overall top-N recall must stay above the threshold.
-const corpus = JSON.parse(await readFile(path.join(root, 'tests', 'discovery', 'corpus.json'), 'utf8'));
-const corpusResults = await evaluateCorpus(loader, corpus, packageInfo.version);
-const recall = corpusResults.filter(r => r.pass).length / corpusResults.length;
-if (recall < corpus.min_recall) fail(`discovery corpus recall ${recall.toFixed(3)} is below ${corpus.min_recall}; run node tests/discovery/run-corpus.mjs for the misses`);
-for (const tool of manifest.tools) {
-  const count = corpus.entries.filter(entry => entry.expect === tool.name).length;
-  if (count < corpus.min_per_tool) fail(`${tool.name}: the discovery corpus needs at least ${corpus.min_per_tool} phrasings (has ${count})`);
-}
-for (const guide of manifest.guidance.filter(g => g.kind === 'workflow'))
-  if (!corpus.entries.some(entry => entry.expect_guidance === guide.name)) fail(`workflow ${guide.name}: the discovery corpus needs at least one phrasing`);
-if (!corpus.entries.some(entry => entry.expect_fallback)) fail('the discovery corpus needs at least one query that must return the capability route');
-
-// 9. Local links in all guidance and contributor documents.
-let localLinkCount = 0;
-for (const file of [...guidanceFiles, path.join(root, 'tests/tool-documentation/README.md')]) {
-  if (!existsSync(file)) continue;
-  const markdown = await readFile(file, 'utf8');
-  const prose = markdown.replace(/^```[^\n]*\r?\n[\s\S]*?^```[ \t]*\r?$/gm, '');
-  for (const match of prose.matchAll(/\[[^\]]*\]\((?:<([^>]+)>|([^\s)]+))(?:\s+"[^"]*")?\)/g)) {
-    const destination = match[1] ?? match[2];
-    if (/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(destination)) continue;
-    const relative = decodeURIComponent(destination.split('#')[0]);
-    if (!relative) continue;
-    try { await access(path.resolve(path.dirname(file), relative)); localLinkCount++; }
-    catch { fail(`${path.relative(root, file)}: broken local link ${destination}`); }
-  }
-}
-
-for (const warning of warnings) console.warn(`WARNING: ${warning}`);
-assert.equal(problems.length, 0, `Platform validation failed:\n${problems.join('\n')}`);
-console.log(`PASS: ${descriptors.length} bridge + ${registered.size - descriptors.length} native contracts; ${manualFiles.length} manuals with generated contracts; ${exampleCount} valid input examples; ${register.invariants.length} invariants; discovery recall ${corpusResults.filter(r => r.pass).length}/${corpusResults.length}; ${localLinkCount} local links.`);
-console.log(`Prompt: platform section ${promptReport.sectionChars} + ${promptReport.activeTools} active tools ${promptReport.toolChars} = ${promptReport.total} characters (budget ${PROMPT_BUDGET.startupTotal}).`);
-console.log('Offline structure verification only: conditional runtime rules, Revit behavior, and agent effectiveness require their own tests.');
-
-function assertDocumentedKeys(schema, value, location) {
-  if (!schema || typeof schema !== 'object' || value === null) return;
-  if (Array.isArray(value)) {
-    if (schema.items) value.forEach((item, index) => assertDocumentedKeys(schema.items, item, `${location}[${index}]`));
-  } else if (typeof value === 'object' && schema.properties) {
-    for (const [key, child] of Object.entries(value)) {
-      // Some schemas permit additional JSON properties, but manual argument examples must use advertised keys.
-      assert.ok(Object.hasOwn(schema.properties, key) || schema.additionalProperties === true || schema.patternProperties,
-        `${location}: undocumented argument ${key}`);
-      if (schema.properties[key]) assertDocumentedKeys(schema.properties[key], child, `${location}.${key}`);
-    }
-  }
-}
-
-async function filesUnder(directory) {
-  const files = [];
-  for (const entry of await readdir(directory, { withFileTypes: true })) {
-    if (['bin', 'obj', 'node_modules'].includes(entry.name)) continue;
-    const file = path.join(directory, entry.name);
-    if (entry.isDirectory()) files.push(...await filesUnder(file));
-    else if (entry.isFile()) files.push(file);
-  }
-  return files;
-}
-
-async function markdownUnder(directory) {
-  return (await filesUnder(directory)).filter(file => file.endsWith('.md'));
-}

package/scripts/generate-contracts.mjs

@@ -1,80 +0,0 @@
-// Generates every derived documentation artifact from code, the single owner of
-// executable contracts:
-//   skills/pi-revit/contracts.generated.json   offline contract snapshot for discovery
-//   "Contract (generated)" block in each tool manual
-//   generated tables in skills/pi-revit/references/tool-index.md
-// Usage: node scripts/generate-contracts.mjs [--check]
-// --check writes nothing and fails when any artifact is stale.
-import { existsSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import {
-  applyIndexBlock, applyManualBlock, createLoader, extractBridgeDescriptors, manifestPath, manualRoot,
-  registerExtension, renderManualBlock, renderToolIndex, resolvePiDependencies, root, snapshotPath, toolIndexPath,
-} from './lib/platform.mjs';
-
-export async function buildArtifacts() {
-  const piRequire = resolvePiDependencies();
-  const loader = createLoader(piRequire);
-  // The extension imports the snapshot; bootstrap an empty one on a first run.
-  if (!existsSync(snapshotPath)) await writeFile(snapshotPath, JSON.stringify({ schema_version: 1, tools: [] }, null, 2) + '\n');
-  const packageInfo = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
-  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
-  const descriptors = await extractBridgeDescriptors();
-  const { contractHash, NATIVE_CONTRACTS, withApiLookups } = await loader.import(path.join(root, 'extensions', 'pi-revit', 'contracts.ts'));
-  const fixture = await registerExtension(loader, descriptors, packageInfo.version);
-  let tools;
-  try {
-    const bridge = new Map(descriptors.map(d => [d.name, d]));
-    tools = [...fixture.registered.keys()].sort().map(name => {
-      const d = bridge.get(name);
-      if (d) return {
-        name, source: 'bridge', tier: d.tier ?? 'core', write: d.write === true, effects: d.effects ?? [], requires_document: d.requiresDocument !== false,
-        document_kinds: d.documentKinds ?? null,
-        keywords: d.keywords ?? [], limits: (d.limits ?? []).map(l => ({ what: l.what, alternative: { kind: l.alternative.kind, ref: l.alternative.ref ?? null } })),
-        verification: d.verification ?? null, contract_hash: contractHash(d), parameters: d.parameters,
-      };
-      const native = NATIVE_CONTRACTS[name];
-      if (!native) throw new Error(`Native tool ${name} has no NATIVE_CONTRACTS entry in extensions/pi-revit/contracts.ts`);
-      const parameters = JSON.parse(JSON.stringify(fixture.registered.get(name).parameters));
-      return {
-        name, source: 'native', tier: 'core', write: native.write, effects: native.effects, requires_document: false, document_kinds: null,
-        keywords: native.keywords, limits: native.limits, verification: native.verification,
-        contract_hash: contractHash({ parameters, write: native.write, effects: native.effects, requiresDocument: false }), parameters,
-      };
-    });
-  } finally { await fixture.restore(); }
-
-  const snapshot = JSON.stringify({
-    schema_version: 1,
-    generated_by: 'scripts/generate-contracts.mjs',
-    note: 'Generated from src/Revit/Tools/*.cs (bridge) and extensions/pi-revit/contracts.ts (native). Do not edit; change the code and regenerate.',
-    tools,
-  }, null, 2) + '\n';
-  const files = new Map([[snapshotPath, snapshot]]);
-  for (const tool of tools) {
-    const file = path.join(manualRoot, `${tool.name}.md`);
-    if (!existsSync(file)) continue; // missing manuals are reported by the documentation checker
-    files.set(file, applyManualBlock(await readFile(file, 'utf8'), renderManualBlock({ ...tool, limits: withApiLookups(tool.limits) })));
-  }
-  files.set(toolIndexPath, applyIndexBlock(await readFile(toolIndexPath, 'utf8'), renderToolIndex(manifest, tools)));
-  return { files, tools, descriptors };
-}
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
-  const check = process.argv.includes('--check');
-  const { files } = await buildArtifacts();
-  const stale = [];
-  for (const [file, content] of files) {
-    const current = existsSync(file) ? await readFile(file, 'utf8') : null;
-    if (current === content) continue;
-    stale.push(path.relative(root, file));
-    if (!check) await writeFile(file, content);
-  }
-  if (check && stale.length) {
-    console.error(`Generated artifacts are stale. Run npm run generate:contracts:\n${stale.join('\n')}`);
-    process.exit(1);
-  }
-  console.log(check ? `Generated artifacts are current (${files.size} files).` : `Updated ${stale.length} of ${files.size} generated artifacts.`);
-}

package/scripts/lib/platform.mjs

@@ -1,226 +0,0 @@
-// Shared offline platform helpers for the contract generator and the documentation
-// checker. Nothing here contacts Revit, the network or a live model: bridge metadata
-// comes from the real C# registry compiled with stubbed tool bodies, and the Pi
-// extension is registered against an isolated fake bridge.
-import { createRequire } from 'node:module';
-import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-export const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-export const skillRoot = path.join(root, 'skills', 'pi-revit');
-export const manualRoot = path.join(skillRoot, 'references', 'tools');
-export const snapshotPath = path.join(skillRoot, 'contracts.generated.json');
-export const manifestPath = path.join(skillRoot, 'tool-manifest.json');
-export const toolIndexPath = path.join(skillRoot, 'references', 'tool-index.md');
-
-export function resolvePiDependencies() {
-  const candidates = [process.env.PI_CODING_AGENT_PATH,
-    path.join(path.dirname(process.execPath), 'node_modules', '@earendil-works', 'pi-coding-agent')].filter(Boolean);
-  for (const candidate of candidates) {
-    const require = createRequire(path.join(path.resolve(candidate), 'package.json'));
-    try { require.resolve('jiti'); require.resolve('typebox/value'); return require; } catch {}
-  }
-  throw new Error('Set PI_CODING_AGENT_PATH to an existing @earendil-works/pi-coding-agent directory containing jiti and typebox. These checks never install dependencies.');
-}
-
-export function createLoader(piRequire) {
-  const { createJiti } = piRequire('jiti');
-  return createJiti(import.meta.url, { alias: { typebox: piRequire.resolve('typebox') }, moduleCache: false });
-}
-
-/** Real ToolRegistry.DescribeAll() output, via the Roslyn schema extractor. */
-export async function extractBridgeDescriptors() {
-  const scratch = await mkdtemp(path.join(os.tmpdir(), 'pi-revit-contracts-'));
-  try {
-    const output = path.join(scratch, 'bridge.json');
-    const run = spawnSync('dotnet', ['run', '--project', path.join(root, 'tests', 'tool-documentation', 'schema-extractor.csproj'), '--', root, output],
-      { cwd: root, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, env: { ...process.env, DOTNET_CLI_TELEMETRY_OPTOUT: '1', DOTNET_SKIP_FIRST_TIME_EXPERIENCE: '1' } });
-    if (run.error || run.status !== 0)
-      throw new Error(`Bridge schema extraction failed (installed .NET SDK 8+ required).\n${run.error?.message ?? ''}\n${run.stdout}\n${run.stderr}`);
-    return JSON.parse(await readFile(output, 'utf8'));
-  } finally { await rm(scratch, { recursive: true, force: true }); }
-}
-
-/**
- * Register the real extension against an in-memory bridge that serves `descriptors`.
- * Returns the registrations and event handlers. Every non-metadata route and all
- * real network access are rejected, and no registered execute() is invoked.
- */
-export async function registerExtension(loader, descriptors, addinVersion) {
-  const scratch = await mkdtemp(path.join(os.tmpdir(), 'pi-revit-register-'));
-  const original = { fetch: globalThis.fetch, appdata: process.env.APPDATA, setInterval: globalThis.setInterval };
-  process.env.APPDATA = scratch;
-  await mkdir(path.join(scratch, 'RevitBridge'));
-  await writeFile(path.join(scratch, 'RevitBridge', 'bridge.json'), JSON.stringify({ baseUrl: 'http://platform-fixture.invalid', token: 'offline-fixture' }));
-  const routes = [];
-  globalThis.fetch = async (input, init) => {
-    const url = new URL(typeof input === 'string' || input instanceof URL ? input : input.url);
-    if (url.origin !== 'http://platform-fixture.invalid') throw new Error('real network access is forbidden');
-    if ((init?.method ?? 'GET') !== 'GET' || !['/ping', '/tools'].includes(url.pathname)) throw new Error(`tool execution is forbidden: ${url.pathname}`);
-    routes.push(url.pathname);
-    return new Response(JSON.stringify(url.pathname === '/tools' ? { tools: descriptors } : { ok: true, addinVersion }));
-  };
-  globalThis.setInterval = () => { throw new Error('Background polling is forbidden in platform fixtures'); };
-  const registered = new Map(), events = new Map();
-  let active = [];
-  const pi = {
-    registerTool(tool) { if (registered.has(tool.name)) throw new Error(`duplicate registered tool ${tool.name}`); registered.set(tool.name, tool); active = [...active, tool.name]; },
-    on(name, handler) { events.set(name, handler); },
-    getActiveTools() { return [...active]; },
-    setActiveTools(names) { active = [...names]; },
-    sendMessage() { throw new Error('Messages are forbidden in platform fixtures'); },
-  };
-  const restore = async () => {
-    await events.get('session_shutdown')?.({}, {});
-    globalThis.fetch = original.fetch; globalThis.setInterval = original.setInterval;
-    if (original.appdata === undefined) delete process.env.APPDATA; else process.env.APPDATA = original.appdata;
-    await rm(scratch, { recursive: true, force: true });
-  };
-  try {
-    const { default: connector } = await loader.import(path.join(root, 'extensions', 'pi-revit', 'index.ts'));
-    await connector(pi);
-  } catch (error) { await restore(); throw error; }
-  return { pi, registered, events, routes, activeTools: () => [...active], restore };
-}
-
-/** Human-readable type, requiredness, default and allowed values of one JSON schema property. */
-function describeProperty(schema) {
-  const values = [];
-  let type = schema?.type;
-  if (Array.isArray(schema?.enum)) values.push(...schema.enum);
-  for (const variant of schema?.anyOf ?? schema?.oneOf ?? []) {
-    if (variant.const !== undefined) { values.push(variant.const); type ??= typeof variant.const; }
-    else if (variant.type) type = type ? `${type} | ${variant.type}` : variant.type;
-  }
-  if (schema?.const !== undefined) values.push(schema.const);
-  if (type === 'array') {
-    const items = schema.items ?? {};
-    const itemValues = Array.isArray(items.enum) ? items.enum : (items.anyOf ?? []).filter(v => v.const !== undefined).map(v => v.const);
-    values.push(...itemValues);
-    type = `array of ${items.type ?? (itemValues.length ? typeof itemValues[0] : 'value')}`;
-  }
-  if (Array.isArray(type)) type = type.join(' | ');
-  return { type: type ?? 'value', values, default: schema?.default };
-}
-
-const VERIFICATION_TEXT = {
-  reread: 'query the changed state again with a read tool',
-  capture: 'capture the visible result and inspect the image',
-  inspect_output: 'open and inspect the produced file',
-  none: 'no durable outcome to check; report what was done',
-};
-const cell = text => String(text).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
-
-export function alternativeText(limit) {
-  const ref = limit.alternative.ref ? cell(limit.alternative.ref) : '';
-  switch (limit.alternative.kind) {
-    case 'tool': return `Tool: ${ref}`;
-    case 'api': return `Revit API: ${ref}. ${limit.lookup ? `Check all its members in one call: \`search_api_docs\` with query \`${cell(limit.lookup.query)}\`` : 'Check with `search_api_docs`'}, then use \`execute_csharp\` within the requested scope.`;
-    case 'user': return `User action: ${ref}`;
-    case 'revit_unsupported': return `Not offered by the Revit API (${ref}). Report this with the evidence checked.`;
-    default: return ref;
-  }
-}
-
-export const CONTRACT_START = '<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->';
-export const CONTRACT_END = '<!-- generated:contract:end -->';
-
-export function renderManualBlock(tool) {
-  const lines = [CONTRACT_START, '## Contract (generated)', ''];
-  const tier = tool.source === 'native' ? 'Pi extension utility, always active'
-    : tool.tier === 'advanced' ? 'bridge tool, advanced tier: activate it with `find_revit_tools`' : 'bridge tool, core tier: active by default';
-  lines.push(`- **Source:** ${tier}.`);
-  lines.push(`- **Writes model:** ${tool.write ? 'yes' : 'no'}. **Effects:** ${tool.effects.length ? tool.effects.join(', ') : 'none'}. **Requires an open document:** ${tool.requires_document ? 'yes' : 'no'}.`);
-  if (tool.document_kinds?.length && tool.requires_document)
-    lines.push(`- **Works in:** ${tool.document_kinds.length > 1 ? 'project and family documents' : `${tool.document_kinds[0]} documents only; the bridge refuses other documents before running, with the route to use instead`}.`);
-  if (tool.verification) lines.push(`- **Verify the outcome:** \`${tool.verification}\`: ${VERIFICATION_TEXT[tool.verification]}.`);
-  lines.push(`- **Contract hash:** \`${tool.contract_hash}\`. \`find_revit_tools\` compares it with the selected bridge's live contract.`);
-  lines.push('', '| Input | Type | Required | Default | Allowed values |', '| --- | --- | --- | --- | --- |');
-  const schema = tool.parameters ?? {};
-  const required = new Set(schema.required ?? []);
-  const properties = Object.entries(schema.properties ?? {});
-  if (!properties.length) lines.push('| _(none)_ | | | | |');
-  for (const [name, property] of properties) {
-    const d = describeProperty(property);
-    lines.push(`| \`${name}\` | ${cell(d.type)} | ${required.has(name) ? 'yes' : 'no'} | ${d.default === undefined ? '' : `\`${cell(JSON.stringify(d.default))}\``} | ${d.values.map(v => `\`${cell(v)}\``).join(', ')} |`);
-  }
-  if (tool.source === 'bridge') lines.push('', 'Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).');
-  if (tool.limits.length) {
-    lines.push('', '| Not covered by this tool | Use instead |', '| --- | --- |');
-    for (const limit of tool.limits) lines.push(`| ${cell(limit.what)} | ${alternativeText(limit)} |`);
-  }
-  lines.push(CONTRACT_END);
-  return lines.join('\n');
-}
-
-/** Replace the generated block, or insert it before the first "## Inputs" heading (else the second H2). */
-export function applyManualBlock(markdown, block) {
-  const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
-  const body = block.replace(/\n/g, eol);
-  const start = markdown.indexOf(CONTRACT_START), end = markdown.indexOf(CONTRACT_END);
-  if (start >= 0 && end > start) return markdown.slice(0, start) + body + markdown.slice(end + CONTRACT_END.length);
-  const headings = [...markdown.matchAll(/^## .*$/gm)];
-  const anchor = headings.find(h => /^## Inputs/.test(h[0])) ?? headings[1];
-  if (!anchor) return markdown.trimEnd() + eol + eol + body + eol;
-  return markdown.slice(0, anchor.index) + body + eol + eol + markdown.slice(anchor.index);
-}
-
-export const INDEX_START = '<!-- generated:tool-index:start (npm run generate:contracts; do not edit this block) -->';
-export const INDEX_END = '<!-- generated:tool-index:end -->';
-
-export function renderToolIndex(manifest, contracts) {
-  const byName = new Map(contracts.map(tool => [tool.name, tool]));
-  const lines = [INDEX_START];
-  for (const group of manifest.groups) {
-    lines.push('', `## ${group.title}`, '', '| Manual | Use | Tier | Verify |', '| --- | --- | --- | --- |');
-    for (const tool of manifest.tools.filter(entry => entry.group === group.id)) {
-      const contract = byName.get(tool.name);
-      const tier = tool.source === 'native' ? 'native' : contract?.tier ?? '';
-      lines.push(`| [${tool.name}](tools/${tool.name}.md) | ${cell(tool.summary)} | ${tier} | ${contract?.verification ?? ''} |`);
-    }
-  }
-  lines.push('', '## Workflows and shared guidance', '', '| Guide | Kind | Use |', '| --- | --- | --- |');
-  for (const guide of manifest.guidance) lines.push(`| [${guide.name}](${guide.path.replace(/^references\//, '')}) | ${guide.kind} | ${cell(guide.summary)} |`);
-  lines.push(INDEX_END);
-  return lines.join('\n');
-}
-
-export function applyIndexBlock(markdown, block) {
-  const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
-  const body = block.replace(/\n/g, eol);
-  const start = markdown.indexOf(INDEX_START), end = markdown.indexOf(INDEX_END);
-  if (start < 0 || end < start) throw new Error(`tool-index.md needs ${INDEX_START} ... ${INDEX_END} markers`);
-  return markdown.slice(0, start) + body + markdown.slice(end + INDEX_END.length);
-}
-
-/**
- * Score the discovery corpus against packaged documentation (no bridge needed).
- * An entry passes when its expected tool or guidance appears in the top_n results,
- * or, for expect_fallback, when the response carries the capability route.
- */
-export async function evaluateCorpus(loader, corpus, addinVersion) {
-  const fixture = await registerExtension(loader, [], addinVersion);
-  try {
-    const find = fixture.registered.get('find_revit_tools');
-    const results = [];
-    for (const entry of corpus.entries) {
-      const response = (await find.execute('corpus', { scope: 'documentation', query: entry.q, limit: corpus.top_n })).details;
-      const tools = response.tools.map(tool => tool.name), guides = response.guidance.map(guide => guide.name);
-      const pass = entry.expect_fallback ? Boolean(response.fallback) && response.match === 'none'
-        : entry.expect_guidance ? guides.slice(0, corpus.top_n).includes(entry.expect_guidance)
-        : tools.slice(0, corpus.top_n).includes(entry.expect);
-      results.push({ ...entry, pass, match: response.match, got: entry.expect_guidance ? guides : tools });
-    }
-    return results;
-  } finally { await fixture.restore(); }
-}
-
-/** Candidate RevitAPI.xml files for optional API-reference verification. */
-export function revitApiXmlPaths() {
-  const roots = [process.env.REVIT_API_PATH, 'C:\\Program Files\\Autodesk\\Revit 2025', 'C:\\Program Files\\Autodesk\\Revit 2026', 'C:\\Program Files\\Autodesk\\Revit 2027'].filter(Boolean);
-  return roots.map(directory => path.join(directory, 'RevitAPI.xml')).filter(file => existsSync(file));
-}

package/scripts/test-extension.mjs

@@ -1,15 +0,0 @@
-import { readdirSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-// Run sequentially: fixtures replace fetch, timers and discovery paths in-process.
-// Each module has a separate process and uses Node's test API directly.
-const directory = new URL('../tests/result-contract/', import.meta.url);
-for (const file of readdirSync(directory).filter(name => name.endsWith('.test.mjs')).sort()) {
-  process.stdout.write(`\n${file}\n`);
-  const result = spawnSync(process.execPath, [fileURLToPath(new URL(file, directory))], {
-    stdio: 'inherit', env: process.env,
-  });
-  if (result.error) throw result.error;
-  if (result.status !== 0) process.exit(result.status ?? 1);
-}