xtrm-tools 0.7.13 → 0.7.15

package/.xtrm/skills/default/specialists-creator/scripts/audit-spec-uniformity.mjs

@@ -0,0 +1,86 @@
+// Audit every .specialist.json under config/specialists/ and .specialists/default/
+// for: (1) schema parse failures, (2) unknown keys that survive .passthrough() silently.
+//
+// Usage (from repo root): bun config/skills/specialists-creator/scripts/audit-spec-uniformity.mjs
+//
+// Keep KNOWN sets in sync with src/specialist/schema.ts. If a sub-schema gains
+// or drops a field, update this file in the same commit.
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = fileURLToPath(import.meta.url);
+const repoRoot = resolve(here, '../../../../..');
+const { validateSpecialist } = await import(resolve(repoRoot, 'src/specialist/schema.ts'));
+
+// Walk known schema keys to detect "unknown" passthrough survivors
+const KNOWN = {
+  root: new Set(['specialist']),
+  specialist: new Set(['metadata','execution','prompt','skills','capabilities','communication','validation','beads_integration','beads_write_notes','stall_detection','heartbeat','mandatory_rules','output_file']),
+  metadata: new Set(['name','version','description','category','author','created','updated','tags']),
+  execution: new Set(['mode','model','fallback_model','timeout_ms','stall_timeout_ms','max_retries','interactive','response_format','output_type','permission_required','requires_worktree','thinking_level','auto_commit','extensions','preferred_profile','approval_mode']),
+  'execution.extensions': new Set(['serena','gitnexus']),
+  prompt: new Set(['system','task_template','normalize_template','output_schema','examples','skill_inherit']),
+  skills: new Set(['paths','scripts']),
+  'skills.scripts.item': new Set(['run','path','phase','inject_output']),
+  capabilities: new Set(['required_tools','external_commands','diagnostic_scripts']),
+  communication: new Set(['next_specialists','publishes']),
+  validation: new Set(['files_to_watch','stale_threshold_days']),
+  stall_detection: new Set(['running_idle_warn_ms','running_idle_kill_ms','waiting_stale_ms','tool_duration_warn_ms']),
+};
+
+function unknownKeys(obj, knownSet, path) {
+  const out = [];
+  for (const k of Object.keys(obj || {})) if (!knownSet.has(k)) out.push(`${path}.${k}`);
+  return out;
+}
+
+function audit(file) {
+  const raw = JSON.parse(readFileSync(file,'utf8'));
+  const findings = [];
+  // raw key check (before parse strips/preserves)
+  findings.push(...unknownKeys(raw, KNOWN.root, ''));
+  const s = raw.specialist ?? {};
+  findings.push(...unknownKeys(s, KNOWN.specialist, 'specialist'));
+  if (s.metadata) findings.push(...unknownKeys(s.metadata, KNOWN.metadata, 'specialist.metadata'));
+  if (s.execution) findings.push(...unknownKeys(s.execution, KNOWN.execution, 'specialist.execution'));
+  if (s.execution?.extensions) findings.push(...unknownKeys(s.execution.extensions, KNOWN['execution.extensions'], 'specialist.execution.extensions'));
+  if (s.prompt) findings.push(...unknownKeys(s.prompt, KNOWN.prompt, 'specialist.prompt'));
+  if (s.skills) findings.push(...unknownKeys(s.skills, KNOWN.skills, 'specialist.skills'));
+  if (Array.isArray(s.skills?.scripts)) for (const [i, sc] of s.skills.scripts.entries()) findings.push(...unknownKeys(sc, KNOWN['skills.scripts.item'], `specialist.skills.scripts[${i}]`));
+  if (s.capabilities) findings.push(...unknownKeys(s.capabilities, KNOWN.capabilities, 'specialist.capabilities'));
+  if (s.communication) findings.push(...unknownKeys(s.communication, KNOWN.communication, 'specialist.communication'));
+  if (s.validation) findings.push(...unknownKeys(s.validation, KNOWN.validation, 'specialist.validation'));
+  if (s.stall_detection) findings.push(...unknownKeys(s.stall_detection, KNOWN.stall_detection, 'specialist.stall_detection'));
+  return findings;
+}
+
+const files = [
+  ...readdirSync(resolve(repoRoot,'config/specialists')).filter(f=>f.endsWith('.specialist.json')).map(f=>join(repoRoot,'config/specialists',f)),
+  ...readdirSync(resolve(repoRoot,'.specialists/default')).filter(f=>f.endsWith('.specialist.json')).map(f=>join(repoRoot,'.specialists/default',f)),
+];
+
+let totalUnknown = 0;
+let parseErrors = 0;
+for (const file of files) {
+  try {
+    const v = await validateSpecialist(readFileSync(file,'utf8'));
+    if (!v.valid) {
+      parseErrors++;
+      console.log(`\n✗ PARSE FAIL ${file}`);
+      for (const e of v.errors) console.log(`    ${e.path}: ${e.message}`);
+      continue;
+    }
+    const unk = audit(file);
+    if (unk.length) {
+      totalUnknown += unk.length;
+      console.log(`\n⚠ ${file}`);
+      for (const k of unk) console.log(`    unknown key: ${k}`);
+    }
+  } catch (e) {
+    parseErrors++;
+    console.log(`\n✗ ERROR ${file}: ${e.message}`);
+  }
+}
+console.log(`\n=== ${files.length} specs · ${parseErrors} parse errors · ${totalUnknown} unknown keys ===`);

package/.xtrm/skills/default/specialists-creator/scripts/scaffold-specialist.ts

@@ -0,0 +1,223 @@
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as z from "zod";
+import { SpecialistSchema } from "../../../../src/specialist/schema.ts";
+
+const DEAD_FIELDS = new Set<string>([]);
+
+interface AddedField {
+  path: string;
+  value: unknown;
+}
+
+interface ScaffoldResult {
+  value: unknown;
+  added: AddedField[];
+  changed: boolean;
+}
+
+function printUsage(): void {
+  console.error("Usage: node scripts/scaffold-specialist.ts <path-to-specialist.json>");
+  console.error("   or: node scripts/scaffold-specialist.ts --all");
+}
+
+function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny {
+  let current = schema;
+  while (
+    current instanceof z.ZodOptional ||
+    current instanceof z.ZodNullable ||
+    current instanceof z.ZodDefault ||
+    current instanceof z.ZodEffects
+  ) {
+    if (current instanceof z.ZodEffects) {
+      current = current.innerType();
+      continue;
+    }
+
+    if (current instanceof z.ZodDefault) {
+      current = current._def.innerType;
+      continue;
+    }
+
+    current = current.unwrap();
+  }
+  return current;
+}
+
+function isOptionalWithoutDefault(schema: z.ZodTypeAny): boolean {
+  if (schema instanceof z.ZodOptional) {
+    return true;
+  }
+  if (schema instanceof z.ZodNullable) {
+    return isOptionalWithoutDefault(schema.unwrap());
+  }
+  if (schema instanceof z.ZodEffects) {
+    return isOptionalWithoutDefault(schema.innerType());
+  }
+  if (schema instanceof z.ZodDefault) {
+    return false;
+  }
+  return false;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  return JSON.stringify(value);
+}
+
+function scaffoldSchema(schema: z.ZodTypeAny, currentValue: unknown, path: string[]): ScaffoldResult {
+  if (schema instanceof z.ZodEffects) {
+    return scaffoldSchema(schema.innerType(), currentValue, path);
+  }
+
+  if (schema instanceof z.ZodDefault) {
+    const inner = schema._def.innerType;
+    if (currentValue === undefined) {
+      const defaultValue = schema._def.defaultValue();
+      const nested = scaffoldSchema(inner, defaultValue, path);
+      return {
+        value: nested.value,
+        added: [{ path: path.join("."), value: nested.value }, ...nested.added],
+        changed: true,
+      };
+    }
+    return scaffoldSchema(inner, currentValue, path);
+  }
+
+  if (schema instanceof z.ZodOptional) {
+    if (currentValue === undefined) {
+      return { value: currentValue, added: [], changed: false };
+    }
+    return scaffoldSchema(schema.unwrap(), currentValue, path);
+  }
+
+  if (schema instanceof z.ZodNullable) {
+    if (currentValue === null || currentValue === undefined) {
+      return { value: currentValue, added: [], changed: false };
+    }
+    return scaffoldSchema(schema.unwrap(), currentValue, path);
+  }
+
+  if (schema instanceof z.ZodArray) {
+    if (currentValue === undefined) {
+      return {
+        value: [],
+        added: [{ path: path.join("."), value: [] }],
+        changed: true,
+      };
+    }
+    return { value: currentValue, added: [], changed: false };
+  }
+
+  if (schema instanceof z.ZodEnum) {
+    return { value: currentValue, added: [], changed: false };
+  }
+
+  if (schema instanceof z.ZodObject) {
+    const source = isRecord(currentValue) ? currentValue : undefined;
+    const draft: Record<string, unknown> = source ? { ...source } : {};
+    const added: AddedField[] = [];
+    let changed = false;
+
+    const shape = schema.shape;
+    for (const [key, childSchema] of Object.entries(shape)) {
+      if (DEAD_FIELDS.has(key)) {
+        continue;
+      }
+
+      const childPath = [...path, key];
+      const childValue = source?.[key];
+      const childResult = scaffoldSchema(childSchema as z.ZodTypeAny, childValue, childPath);
+
+      if (!childResult.changed) {
+        continue;
+      }
+
+      draft[key] = childResult.value;
+      added.push(...childResult.added);
+      changed = true;
+    }
+
+    if (!source) {
+      if (!changed || isOptionalWithoutDefault(schema)) {
+        return { value: currentValue, added, changed: false };
+      }
+      return { value: draft, added, changed: true };
+    }
+
+    return { value: changed ? draft : currentValue, added, changed };
+  }
+
+  const unwrapped = unwrapSchema(schema);
+  if (
+    unwrapped instanceof z.ZodString ||
+    unwrapped instanceof z.ZodNumber ||
+    unwrapped instanceof z.ZodBoolean
+  ) {
+    return { value: currentValue, added: [], changed: false };
+  }
+
+  return { value: currentValue, added: [], changed: false };
+}
+
+function loadTargets(arg: string): string[] {
+  if (arg !== "--all") {
+    return [arg];
+  }
+
+  const specialistsDir = join(process.cwd(), "config", "specialists");
+  return readdirSync(specialistsDir)
+    .filter(file => file.endsWith(".specialist.json"))
+    .sort()
+    .map(file => join(specialistsDir, file));
+}
+
+function processFile(filePath: string): AddedField[] {
+  const raw = readFileSync(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+
+  if (!isRecord(parsed)) {
+    throw new Error(`Expected JSON object in ${filePath}`);
+  }
+
+  const result = scaffoldSchema(SpecialistSchema, parsed, []);
+  if (!result.changed) {
+    return [];
+  }
+
+  writeFileSync(filePath, `${JSON.stringify(result.value, null, 2)}\n`, "utf8");
+  return result.added;
+}
+
+function run(): void {
+  const targetArg = process.argv[2];
+  if (!targetArg) {
+    printUsage();
+    process.exit(64);
+  }
+
+  const targets = loadTargets(targetArg);
+  if (targets.length === 0) {
+    console.log("No specialist files found.");
+    return;
+  }
+
+  for (const filePath of targets) {
+    const addedFields = processFile(filePath);
+    if (addedFields.length === 0) {
+      continue;
+    }
+
+    for (const field of addedFields) {
+      console.log(`${filePath}: ${field.path} = ${formatValue(field.value)}`);
+    }
+  }
+}
+
+run();

package/.xtrm/skills/default/specialists-creator/scripts/validate-specialist.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { parseSpecialist } from "../../../src/specialist/schema.ts";
+import { parseSpecialist } from "../../../../src/specialist/schema.ts";
 
 function printUsage(): void {
   console.error("Usage: bun skills/specialist-author/scripts/validate-specialist.ts <path-to.specialist.yaml>");