@disclosureos/cli 1.0.0

package/dist/index.js

@@ -0,0 +1,1358 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+// src/utils/args.ts
+var SHORT_FLAG_MAP = {
+  o: "out",
+  h: "help",
+  v: "version",
+  r: "recursive",
+  s: "strict",
+  j: "json"
+};
+var VALUE_FLAGS = /* @__PURE__ */ new Set(["out", "category", "id"]);
+function assignFlag(key, args2, index, flags) {
+  if (VALUE_FLAGS.has(key)) {
+    const next = args2[index + 1];
+    if (next !== void 0 && !next.startsWith("-")) {
+      flags[key] = next;
+      return index + 1;
+    }
+  }
+  flags[key] = true;
+  return index;
+}
+function parseArgs(argv) {
+  const args2 = argv.slice(2);
+  const positional = [];
+  const flags = {};
+  let command = "help";
+  let subcommand = "";
+  let positionsFilled = 0;
+  for (let i = 0; i < args2.length; i++) {
+    const arg = args2[i];
+    if (arg.startsWith("--")) {
+      i = assignFlag(arg.slice(2), args2, i, flags);
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const longKey = SHORT_FLAG_MAP[arg[1]] ?? arg[1];
+      i = assignFlag(longKey, args2, i, flags);
+    } else if (positionsFilled === 0) {
+      command = arg;
+      positionsFilled++;
+    } else if (positionsFilled === 1) {
+      subcommand = arg;
+      positionsFilled++;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { command, subcommand, positional, flags };
+}
+
+// src/output/templates.ts
+function uuid() {
+  return globalThis.crypto.randomUUID();
+}
+function buildObservation(full) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const minimal = {
+    id: uuid(),
+    temporal: {
+      date: "2024-01-01",
+      dateCertainty: "exact",
+      timeOfDay: "night"
+    },
+    location: {
+      id: uuid(),
+      name: "Untitled Observation",
+      country: "Unknown",
+      latitude: 0,
+      longitude: 0,
+      siteType: "unknown",
+      terrain: "unknown"
+    },
+    status: "draft",
+    createdAt: now,
+    updatedAt: now,
+    summary: ""
+  };
+  if (!full) return minimal;
+  return {
+    ...minimal,
+    temporal: {
+      date: "2024-01-01",
+      dateCertainty: "exact",
+      timeOfDay: "night",
+      durationSeconds: 0
+    },
+    location: {
+      id: uuid(),
+      name: "Untitled Observation",
+      country: "Unknown",
+      latitude: 0,
+      longitude: 0,
+      siteType: "unknown",
+      terrain: "unknown",
+      elevationMeters: 0,
+      coordinatesApproximate: false,
+      locationSensitivity: "none"
+    },
+    description: "",
+    objectCharacteristics: {
+      shape: "unknown",
+      color: "",
+      size: "",
+      luminosity: "",
+      sound: "",
+      numberObserved: 1
+    },
+    eventType: "",
+    sourceData: { sources: [] },
+    investigation: {
+      investigatingBody: "",
+      caseNumber: "",
+      conclusion: "",
+      confidence: "unassessed"
+    },
+    movement: { speed: "", maneuvers: [] },
+    witnesses: { count: 0, categories: [] },
+    sensorEvidence: { sensors: [], multiSensorCorrelation: false },
+    environment: { weather: "", visibility: "" },
+    media: [],
+    relations: { edges: [] },
+    dataSourceId: "",
+    schemaVersion: "1.0.0"
+  };
+}
+var ASSESSMENT_TEMPLATE = {
+  technology: {
+    antigravity_lift: [
+      { level: "not_indicated", rationale: "", evidenceRefs: [] }
+    ],
+    instantaneous_acceleration: [{ level: "not_indicated", rationale: "" }],
+    hypersonic_no_signatures: [{ level: "not_indicated", rationale: "" }],
+    low_observability: [{ level: "not_indicated", rationale: "" }],
+    transmedium_travel: [{ level: "not_indicated", rationale: "" }],
+    biological_effects: [{ level: "not_indicated", rationale: "" }]
+  },
+  biologics: {
+    molecular_complexity: [{ level: "not_indicated", rationale: "" }],
+    isotopic_provenance: [{ level: "not_indicated", rationale: "" }],
+    non_standard_biochemistry: [{ level: "not_indicated", rationale: "" }],
+    non_phylogenetic_genetics: [{ level: "not_indicated", rationale: "" }],
+    anomalous_morphology: [{ level: "not_indicated", rationale: "" }],
+    anomalous_bio_interaction: [{ level: "not_indicated", rationale: "" }]
+  }
+};
+var CLASSIFICATION_TEMPLATE = [
+  {
+    primaryHypothesis: "1.1.1",
+    confidence: 0.5,
+    alternativeHypotheses: [{ nodeId: "1.1.3", confidence: 0.2 }],
+    rationale: "",
+    evaluatedBy: "",
+    evidenceRefs: []
+  }
+];
+function getTemplate(name) {
+  const data = name === "observation" ? buildObservation(false) : name === "observation-full" ? buildObservation(true) : name === "assessment" ? ASSESSMENT_TEMPLATE : CLASSIFICATION_TEMPLATE;
+  return JSON.stringify(data, null, 2);
+}
+
+// src/utils/fs.ts
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from "fs";
+import { resolve, extname } from "path";
+function readJSON(filePath) {
+  const content = readFileSync(resolve(filePath), "utf-8");
+  return JSON.parse(content);
+}
+function writeOutput(filePath, data) {
+  const content = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+  writeFileSync(resolve(filePath), content + "\n", "utf-8");
+}
+function findJSONFiles(dirPath, recursive) {
+  const resolved = resolve(dirPath);
+  if (!existsSync(resolved)) return [];
+  const stat = statSync(resolved);
+  if (stat.isFile()) {
+    return extname(resolved) === ".json" ? [resolved] : [];
+  }
+  const results = [];
+  const entries = readdirSync(resolved, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = resolve(resolved, entry.name);
+    if (entry.isFile() && extname(entry.name) === ".json") {
+      results.push(entryPath);
+    } else if (entry.isDirectory() && recursive) {
+      results.push(...findJSONFiles(entryPath, true));
+    }
+  }
+  return results;
+}
+
+// src/output/format.ts
+import pc from "picocolors";
+var BRAND = pc.bold(pc.cyan("DisclosureOS"));
+function heading(text) {
+  return `
+${pc.bold(pc.white(text))}
+${"\u2500".repeat(text.length)}`;
+}
+function success(text) {
+  return pc.green(`\u2713 ${text}`);
+}
+function error(text) {
+  return pc.red(`\u2717 ${text}`);
+}
+function warn(text) {
+  return pc.yellow(`\u26A0 ${text}`);
+}
+function dim(text) {
+  return pc.dim(text);
+}
+function label(key, value) {
+  return `  ${pc.bold(key)}: ${value}`;
+}
+function bullet(text) {
+  return `  ${pc.dim("\u2022")} ${text}`;
+}
+function table(rows, gutter = 2) {
+  const maxKey = Math.max(...rows.map(([k]) => k.length));
+  return rows.map(([k, v]) => `  ${pc.bold(k.padEnd(maxKey + gutter))}${v}`).join("\n");
+}
+
+// src/commands/scaffold.ts
+var VALID_TEMPLATES = ["observation", "observation-full", "assessment", "classification"];
+function scaffold(args2) {
+  if (args2.flags["help"]) {
+    printUsage();
+    return;
+  }
+  const templateName = resolveTemplateName(args2);
+  if (!templateName) {
+    printUsage();
+    return;
+  }
+  const asTypeScript = !!args2.flags["ts"];
+  const content = asTypeScript ? getTypeScriptTemplate(templateName) : getTemplate(templateName);
+  const outputPath = args2.flags["out"];
+  if (outputPath && typeof outputPath === "string") {
+    writeOutput(outputPath, content);
+    console.log(success(`Wrote ${templateName} template to ${outputPath}`));
+  } else {
+    console.log(content);
+  }
+}
+function resolveTemplateName(args2) {
+  const sub = args2.subcommand;
+  if (!sub) return null;
+  if (sub === "observation") {
+    return args2.flags["full"] ? "observation-full" : "observation";
+  }
+  if (VALID_TEMPLATES.includes(sub)) {
+    return sub;
+  }
+  console.log(error(`Unknown template: "${sub}"`));
+  return null;
+}
+function getTypeScriptTemplate(name) {
+  switch (name) {
+    case "observation":
+      return TS_OBSERVATION;
+    case "observation-full":
+      return TS_OBSERVATION_FULL;
+    case "assessment":
+      return TS_ASSESSMENT;
+    case "classification":
+      return TS_CLASSIFICATION;
+  }
+}
+var TS_OBSERVATION = `import { createObservation } from '@disclosureos/records/factories';
+
+// createObservation auto-generates id, location.id, and timestamps.
+export const observation = createObservation(
+  {
+    temporal: {
+      date: '2024-01-01',
+      dateCertainty: 'exact',
+      timeOfDay: 'night',
+    },
+    location: {
+      name: '',
+      country: '',
+      latitude: 0,
+      longitude: 0,
+      siteType: 'unknown',
+    },
+    summary: '',
+  },
+  { status: 'draft' },
+);
+`;
+var TS_OBSERVATION_FULL = `import { createObservation } from '@disclosureos/records/factories';
+
+// createObservation auto-generates id, location.id, and timestamps.
+export const observation = createObservation(
+  {
+    temporal: {
+      date: '2024-01-01',
+      dateCertainty: 'exact',
+      timeOfDay: 'night',
+      durationSeconds: 0,
+    },
+    location: {
+      name: '',
+      country: '',
+      latitude: 0,
+      longitude: 0,
+      siteType: 'unknown',
+      terrain: 'unknown',
+    },
+    summary: '',
+    description: '',
+    objectCharacteristics: {
+      shape: 'unknown',
+      color: '',
+      numberObserved: 1,
+    },
+    eventType: '',
+    sourceData: { sources: [] },
+    investigation: {
+      investigatingBody: '',
+      conclusion: '',
+      confidence: 'unassessed',
+    },
+    movement: { maneuvers: [] },
+    witnesses: { count: 0, categories: [] },
+    sensorEvidence: { sensors: [], multiSensorCorrelation: false },
+    environment: { weather: '', visibility: '' },
+    media: [],
+    schemaVersion: '1.0.0',
+  },
+  { status: 'draft' },
+);
+`;
+var TS_ASSESSMENT = `import type { ObservableAssessmentMap } from '@disclosureos/observables';
+import { createObservableClaim } from '@disclosureos/observables';
+
+// Each observable maps to a *list* of claims, so competing verdicts coexist.
+// Pass evidenceRefs (e.g. ['sensor:<id>']) to link a claim to in-record evidence.
+export const assessment: ObservableAssessmentMap = {
+  technology: {
+    antigravity_lift: [createObservableClaim('not_indicated')],
+    instantaneous_acceleration: [createObservableClaim('not_indicated')],
+    hypersonic_no_signatures: [createObservableClaim('not_indicated')],
+    low_observability: [createObservableClaim('not_indicated')],
+    transmedium_travel: [createObservableClaim('not_indicated')],
+    biological_effects: [createObservableClaim('not_indicated')],
+  },
+  biologics: {
+    molecular_complexity: [createObservableClaim('not_indicated')],
+    isotopic_provenance: [createObservableClaim('not_indicated')],
+    non_standard_biochemistry: [createObservableClaim('not_indicated')],
+    non_phylogenetic_genetics: [createObservableClaim('not_indicated')],
+    anomalous_morphology: [createObservableClaim('not_indicated')],
+    anomalous_bio_interaction: [createObservableClaim('not_indicated')],
+  },
+};
+`;
+var TS_CLASSIFICATION = `import { createOriginClaim } from '@disclosureos/origins';
+import type { OriginClassificationSlot } from '@disclosureos/origins';
+
+// The origin slot is a *list* of competing classifications (one per evaluator).
+// Replace '1.1.1' with your primary OCS node ID; createOriginClaim validates
+// node IDs and confidence at runtime.
+export const classification: OriginClassificationSlot = [
+  createOriginClaim('1.1.1', 0.5, {
+    alternativeHypotheses: [{ nodeId: '1.1.3', confidence: 0.2 }],
+    rationale: '',
+  }),
+];
+`;
+function printUsage() {
+  console.log(heading(`${BRAND} scaffold`));
+  console.log(`
+Generate typed templates for DisclosureOS data structures.
+`);
+  console.log(`${dim("Usage:")}`);
+  console.log(`  disclosureos scaffold <template> [options]
+`);
+  console.log(`${dim("Templates:")}`);
+  console.log(`  observation          Minimal Observation (required fields only)`);
+  console.log(`  observation --full   Complete Observation with all optional fields`);
+  console.log(`  assessment           Observable assessment map (tech + biologics)`);
+  console.log(`  classification       Origin classification assignment
+`);
+  console.log(`${dim("Options:")}`);
+  console.log(`  --out, -o <path>     Write to file instead of stdout`);
+  console.log(`  --ts                 Output as TypeScript (with typed imports)`);
+  console.log(`  --help, -h           Show this help message
+`);
+}
+
+// src/commands/validate.ts
+import { parseEvidenceRef } from "@disclosureos/records/shared";
+import { parseEnrichedObservation } from "@disclosureos/schema";
+function validate(args2) {
+  if (args2.flags["help"]) {
+    printUsage2();
+    return;
+  }
+  const targets = [args2.subcommand, ...args2.positional].filter((t) => !!t);
+  if (targets.length === 0) {
+    printUsage2();
+    return;
+  }
+  const recursive = !!args2.flags["recursive"];
+  const strict = !!args2.flags["strict"];
+  const jsonMode = !!args2.flags["json"];
+  const seen = /* @__PURE__ */ new Set();
+  const files = [];
+  const emptyTargets = [];
+  for (const target of targets) {
+    const found = findJSONFiles(target, recursive);
+    if (found.length === 0) {
+      emptyTargets.push(target);
+      continue;
+    }
+    for (const f of found) {
+      if (!seen.has(f)) {
+        seen.add(f);
+        files.push(f);
+      }
+    }
+  }
+  if (jsonMode) {
+    runJsonMode(files, emptyTargets, strict);
+    return;
+  }
+  for (const t of emptyTargets) {
+    console.log(error(`No JSON files found at: ${t}`));
+  }
+  if (files.length === 0) {
+    process.exit(1);
+  }
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  for (const file of files) {
+    const { errors: fileErrors, warnings } = validateFile(file, strict);
+    totalErrors += fileErrors;
+    totalWarnings += warnings;
+  }
+  console.log("");
+  if (totalErrors === 0 && emptyTargets.length === 0) {
+    const warnSuffix = totalWarnings > 0 ? ` (${totalWarnings} warning${totalWarnings > 1 ? "s" : ""})` : "";
+    console.log(success(`All ${files.length} file(s) valid${warnSuffix}`));
+  } else {
+    if (totalErrors > 0) {
+      console.log(error(`${totalErrors} error(s) across ${files.length} file(s)`));
+    }
+    if (emptyTargets.length > 0) {
+      console.log(error(`${emptyTargets.length} path(s) matched no JSON file`));
+    }
+    process.exit(1);
+  }
+}
+function runJsonMode(files, emptyTargets, strict) {
+  const fileResults = [];
+  for (const file of files) {
+    fileResults.push(validateFileStructured(file, strict));
+  }
+  const totalErrors = fileResults.reduce((sum, r) => sum + r.errors.length, 0);
+  const totalWarnings = fileResults.reduce((sum, r) => sum + r.warnings.length, 0);
+  const output = {
+    files: fileResults,
+    emptyTargets,
+    totals: {
+      files: files.length,
+      errors: totalErrors,
+      warnings: totalWarnings,
+      emptyTargets: emptyTargets.length
+    },
+    valid: totalErrors === 0 && emptyTargets.length === 0
+  };
+  console.log(JSON.stringify(output, null, 2));
+  if (!output.valid) {
+    process.exit(1);
+  }
+}
+function validateFileStructured(filePath, strict) {
+  let data;
+  try {
+    data = readJSON(filePath);
+  } catch {
+    return {
+      file: filePath,
+      valid: false,
+      errors: [{ path: "", message: "Failed to parse JSON" }],
+      warnings: []
+    };
+  }
+  if (!data || typeof data !== "object") {
+    return {
+      file: filePath,
+      valid: false,
+      errors: [{ path: "", message: "Not a valid JSON object" }],
+      warnings: []
+    };
+  }
+  const obs = data;
+  const structuralErrors = parseEnrichedObservation(obs).issues;
+  const semanticErrors = validateSemantics(obs);
+  const warnings = [...validateEvidenceRefs(obs), ...strict ? validateStrict(obs) : []];
+  const allErrors = [...structuralErrors, ...semanticErrors];
+  return {
+    file: filePath,
+    valid: allErrors.length === 0,
+    errors: allErrors.map((e) => ({ path: e.path, message: e.message })),
+    warnings: warnings.map((w) => ({ path: w.path, message: w.message }))
+  };
+}
+function validateFile(filePath, strict) {
+  let data;
+  try {
+    data = readJSON(filePath);
+  } catch {
+    console.log(error(`Failed to parse: ${filePath}`));
+    return { errors: 1, warnings: 0 };
+  }
+  if (!data || typeof data !== "object") {
+    console.log(error(`${filePath}: not a valid JSON object`));
+    return { errors: 1, warnings: 0 };
+  }
+  const obs = data;
+  const structuralErrors = parseEnrichedObservation(obs).issues;
+  const semanticErrors = validateSemantics(obs);
+  const warnings = [...validateEvidenceRefs(obs), ...strict ? validateStrict(obs) : []];
+  const allErrors = [...structuralErrors, ...semanticErrors];
+  if (allErrors.length > 0 || warnings.length > 0) {
+    console.log(`
+${dim(filePath)}`);
+    for (const e of allErrors) {
+      console.log(`  ${error(`${e.path}: ${e.message}`)}`);
+    }
+    for (const w of warnings) {
+      console.log(`  ${warn(`${w.path}: ${w.message}`)}`);
+    }
+  }
+  return { errors: allErrors.length, warnings: warnings.length };
+}
+var EVIDENCE_ID_KEY = {
+  media: "id",
+  sensor: "id",
+  physical: "id",
+  testimony: "statementId"
+};
+function readId(item, key) {
+  if (item && typeof item === "object") {
+    const value = item[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return void 0;
+}
+function addIds(set, items, key) {
+  if (!Array.isArray(items)) return;
+  for (const item of items) {
+    const id = readId(item, key);
+    if (id) set.add(id);
+  }
+}
+function collectEvidenceIds(obs) {
+  const ids = {
+    media: /* @__PURE__ */ new Set(),
+    sensor: /* @__PURE__ */ new Set(),
+    physical: /* @__PURE__ */ new Set(),
+    testimony: /* @__PURE__ */ new Set()
+  };
+  addIds(ids.media, obs["media"], "id");
+  const featured = readId(obs["featuredMedia"], "id");
+  if (featured) ids.media.add(featured);
+  const sensorEvidence = obs["sensorEvidence"];
+  if (sensorEvidence && typeof sensorEvidence === "object") {
+    addIds(ids.sensor, sensorEvidence["sensors"], "id");
+  }
+  addIds(ids.physical, obs["physicalEvidence"], "id");
+  addIds(ids.testimony, obs["testimony"], "statementId");
+  return ids;
+}
+function collectClaimRefs(obs) {
+  const out = [];
+  const pushClaim = (path, claim) => {
+    if (!claim || typeof claim !== "object") return;
+    const refs = claim["evidenceRefs"];
+    if (Array.isArray(refs)) {
+      out.push({ path, refs: refs.filter((r) => typeof r === "string") });
+    }
+  };
+  const assessments = obs["observableAssessments"];
+  if (assessments && typeof assessments === "object") {
+    for (const domain of ["technology", "biologics"]) {
+      const group = assessments[domain];
+      if (!group || typeof group !== "object") continue;
+      for (const [observableId, claims] of Object.entries(group)) {
+        if (Array.isArray(claims)) {
+          claims.forEach((c, i) => pushClaim(`observableAssessments.${domain}.${observableId}[${i}]`, c));
+        }
+      }
+    }
+  }
+  if (Array.isArray(obs["origin"])) {
+    obs["origin"].forEach((c, i) => pushClaim(`origin[${i}]`, c));
+  }
+  return out;
+}
+function validateEvidenceRefs(obs) {
+  const warnings = [];
+  const available = collectEvidenceIds(obs);
+  for (const { path, refs } of collectClaimRefs(obs)) {
+    refs.forEach((ref, i) => {
+      const refPath = `${path}.evidenceRefs[${i}]`;
+      const parsed = parseEvidenceRef(ref);
+      if (!parsed) {
+        warnings.push({ path: refPath, message: `malformed evidence ref "${ref}" (expected "<kind>:<id>")` });
+        return;
+      }
+      const pool = available[parsed.kind];
+      const key = EVIDENCE_ID_KEY[parsed.kind] ?? "id";
+      if (!pool || !pool.has(parsed.id)) {
+        warnings.push({
+          path: refPath,
+          message: `dangling evidence ref "${ref}" \u2014 no ${parsed.kind} with ${key} "${parsed.id}" in record`
+        });
+      }
+    });
+  }
+  return warnings;
+}
+function validateStrict(obs) {
+  const warnings = [];
+  const recommended = ["summary", "description", "objectCharacteristics", "sourceData", "witnesses"];
+  for (const field of recommended) {
+    if (obs[field] == null) {
+      warnings.push({ path: field, message: `recommended field missing (strict mode)` });
+    }
+  }
+  return warnings;
+}
+function validateSemantics(obs) {
+  const errors = [];
+  const numericField = (parent, key, path, { min }) => {
+    if (parent == null || typeof parent !== "object") return;
+    const value = parent[key];
+    if (typeof value === "number" && value < min) {
+      errors.push({ path, message: `${key} cannot be less than ${min}` });
+    }
+  };
+  numericField(obs["temporal"], "durationSeconds", "temporal.durationSeconds", { min: 0 });
+  numericField(obs["movement"], "speedKmh", "movement.speedKmh", { min: 0 });
+  numericField(obs["movement"], "altitudeMeters", "movement.altitudeMeters", { min: 0 });
+  numericField(obs["witnesses"], "count", "witnesses.count", { min: 0 });
+  numericField(obs["objectCharacteristics"], "numberObserved", "objectCharacteristics.numberObserved", { min: 0 });
+  return errors;
+}
+function printUsage2() {
+  console.log(heading(`${BRAND} validate`));
+  console.log(`
+Validate observation JSON files against the full schema.
+`);
+  console.log(`${dim("Usage:")}`);
+  console.log(`  disclosureos validate <path...> [options]
+`);
+  console.log(`${dim("Paths:")}`);
+  console.log(`  Accepts one or more files, directories, or shell globs. Results are`);
+  console.log(`  deduped, and any path matching no JSON fails the run (never silently skipped).
+`);
+  console.log(`${dim("Options:")}`);
+  console.log(`  --recursive, -r      Validate all JSON files in directories recursively`);
+  console.log(`  --strict, -s         Warn on missing recommended fields`);
+  console.log(`  --json, -j           Output results as structured JSON (for CI and scripts)`);
+  console.log(`  --help, -h           Show this help message
+`);
+  console.log(`${dim("Validation checks:")}`);
+  console.log(`  \u2022 Required fields (id, temporal, location, status, createdAt, updatedAt)`);
+  console.log(`  \u2022 Temporal type correctness (ISO date, certainty, granularity, range, relative)`);
+  console.log(`  \u2022 Observable assessment levels and IDs (if present)`);
+  console.log(`  \u2022 OCS node IDs in origin classifications (if present)`);
+  console.log(`  \u2022 Unknown top-level keys rejected (third-party data belongs under "extensions")`);
+  console.log(`  \u2022 Evidence refs on claims resolve to in-record evidence (warns on dangling)`);
+  console.log(`  \u2022 Semantic sanity (non-negative duration, speed, counts)
+`);
+  console.log(`${dim("Examples:")}`);
+  console.log(`  disclosureos validate ./data/nimitz.json`);
+  console.log(`  disclosureos validate ./data/ --recursive`);
+  console.log(`  disclosureos validate ./data/*.json`);
+  console.log(`  disclosureos validate ./data/*.json --json`);
+  console.log(`  disclosureos validate ./a.json ./b.json --strict
+`);
+}
+
+// src/commands/completeness.ts
+import { parseEnrichedObservation as parseEnrichedObservation2 } from "@disclosureos/schema";
+import { getCompleteness } from "@disclosureos/scoring";
+function completeness(args2) {
+  if (args2.flags["help"]) {
+    printUsage3();
+    return;
+  }
+  const targets = [args2.subcommand, ...args2.positional].filter((t) => !!t);
+  if (targets.length === 0) {
+    printUsage3();
+    return;
+  }
+  const recursive = !!args2.flags["recursive"];
+  const jsonMode = !!args2.flags["json"];
+  const seen = /* @__PURE__ */ new Set();
+  const files = [];
+  const emptyTargets = [];
+  for (const target of targets) {
+    const found = findJSONFiles(target, recursive);
+    if (found.length === 0) {
+      emptyTargets.push(target);
+      continue;
+    }
+    for (const f of found) {
+      if (!seen.has(f)) {
+        seen.add(f);
+        files.push(f);
+      }
+    }
+  }
+  if (jsonMode) {
+    runJsonMode2(files, emptyTargets);
+    return;
+  }
+  for (const t of emptyTargets) {
+    console.log(error(`No JSON files found at: ${t}`));
+  }
+  if (files.length === 0) {
+    process.exit(1);
+  }
+  let hasErrors = false;
+  const percentages = [];
+  const reqPercentages = [];
+  for (const file of files) {
+    const result = scoreFile(file);
+    if (!result.valid) {
+      hasErrors = true;
+      continue;
+    }
+    percentages.push(result.percentage);
+    reqPercentages.push(result.requiredPercentage);
+  }
+  console.log("");
+  if (hasErrors || emptyTargets.length > 0) {
+    console.log(error("Some files could not be scored (see errors above)."));
+    process.exit(1);
+  }
+  const mean = avg(percentages);
+  const reqMean = avg(reqPercentages);
+  console.log(
+    success(
+      `${files.length} file(s) scored \u2014 mean completeness ${mean}%, required fields ${reqMean}%`
+    )
+  );
+}
+function avg(values) {
+  return values.length > 0 ? Math.round(values.reduce((a, b) => a + b, 0) / values.length) : 0;
+}
+function scoreFile(filePath) {
+  let data;
+  try {
+    data = readJSON(filePath);
+  } catch {
+    console.log(error(`Failed to parse: ${filePath}`));
+    return emptyResult(filePath, "Failed to parse JSON");
+  }
+  if (!data || typeof data !== "object") {
+    console.log(error(`${filePath}: not a valid JSON object`));
+    return emptyResult(filePath, "Not a valid JSON object");
+  }
+  const parsed = parseEnrichedObservation2(data);
+  if (!parsed.success) {
+    console.log(error(`${filePath}: invalid observation (${parsed.issues.length} issue${parsed.issues.length !== 1 ? "s" : ""})`));
+    for (const issue of parsed.issues.slice(0, 5)) {
+      console.log(`  ${dim(`${issue.path}: ${issue.message}`)}`);
+    }
+    return emptyResult(filePath, "Invalid observation");
+  }
+  const comp = getCompleteness(data);
+  console.log(`
+${dim(filePath)}`);
+  console.log(`  Completeness: ${comp.percentage}%  (${comp.present}/${comp.total} fields)`);
+  console.log(`  Required:     ${comp.requiredPercentage}%  (${comp.requiredPresent}/${comp.requiredTotal})`);
+  if (comp.missing.length > 0) {
+    const shown = comp.missing.slice(0, 10);
+    console.log(`  Missing (top ${shown.length}):`);
+    for (const path of shown) {
+      console.log(`    ${dim("\u2022")} ${path}`);
+    }
+    if (comp.missing.length > shown.length) {
+      console.log(`    ${dim(`\u2026 and ${comp.missing.length - shown.length} more`)}`);
+    }
+  }
+  return {
+    file: filePath,
+    valid: true,
+    percentage: comp.percentage,
+    requiredPercentage: comp.requiredPercentage,
+    present: comp.present,
+    total: comp.total,
+    missing: comp.missing
+  };
+}
+function emptyResult(file, errorMsg) {
+  return {
+    file,
+    valid: false,
+    percentage: 0,
+    requiredPercentage: 0,
+    present: 0,
+    total: 0,
+    missing: [],
+    error: errorMsg
+  };
+}
+function runJsonMode2(files, emptyTargets) {
+  const fileResults = [];
+  for (const file of files) {
+    fileResults.push(scoreFileQuiet(file));
+  }
+  const validResults = fileResults.filter((r) => r.valid);
+  const meanPercentage = avg(validResults.map((r) => r.percentage));
+  const meanRequired = avg(validResults.map((r) => r.requiredPercentage));
+  const allValid = fileResults.every((r) => r.valid) && emptyTargets.length === 0;
+  const output = {
+    files: fileResults,
+    emptyTargets,
+    totals: {
+      files: files.length,
+      meanPercentage,
+      meanRequiredPercentage: meanRequired,
+      emptyTargets: emptyTargets.length
+    },
+    valid: allValid
+  };
+  console.log(JSON.stringify(output, null, 2));
+  if (!allValid) {
+    process.exit(1);
+  }
+}
+function scoreFileQuiet(filePath) {
+  let data;
+  try {
+    data = readJSON(filePath);
+  } catch {
+    return emptyResult(filePath, "Failed to parse JSON");
+  }
+  if (!data || typeof data !== "object") {
+    return emptyResult(filePath, "Not a valid JSON object");
+  }
+  const parsed = parseEnrichedObservation2(data);
+  if (!parsed.success) {
+    return emptyResult(filePath, `Invalid observation (${parsed.issues.length} issue${parsed.issues.length !== 1 ? "s" : ""})`);
+  }
+  const comp = getCompleteness(data);
+  return {
+    file: filePath,
+    valid: true,
+    percentage: comp.percentage,
+    requiredPercentage: comp.requiredPercentage,
+    present: comp.present,
+    total: comp.total,
+    missing: comp.missing
+  };
+}
+function printUsage3() {
+  console.log(heading(`${BRAND} completeness`));
+  console.log(`
+Measure how fully observation JSON files populate the records schema.
+`);
+  console.log(`${dim("Usage:")}`);
+  console.log(`  disclosureos completeness <path...> [options]
+`);
+  console.log(`${dim("Paths:")}`);
+  console.log(`  Accepts one or more files, directories, or shell globs.
+`);
+  console.log(`${dim("Options:")}`);
+  console.log(`  --recursive, -r      Score all JSON files in directories recursively`);
+  console.log(`  --json, -j           Output results as structured JSON (for CI and scripts)`);
+  console.log(`  --help, -h           Show this help message
+`);
+  console.log(`${dim("Scoring:")}`);
+  console.log(`  Files must be structurally valid observations before completeness is measured.`);
+  console.log(`  Invalid JSON or invalid observations exit non-zero without a score.
+`);
+  console.log(`${dim("Output:")}`);
+  console.log(`  \u2022 Completeness percentage (0\u2013100) \u2014 how many schema fields are populated`);
+  console.log(`  \u2022 Required field percentage \u2014 coverage of required fields only`);
+  console.log(`  \u2022 Top missing field paths \u2014 the next fields to target
+`);
+  console.log(`${dim("Examples:")}`);
+  console.log(`  disclosureos completeness ./data/nimitz.json`);
+  console.log(`  disclosureos completeness ./data/ --recursive`);
+  console.log(`  disclosureos completeness ./out/*.json --json
+`);
+}
+
+// src/commands/registry.ts
+import { deriveFieldPaths } from "@disclosureos/scoring";
+import {
+  ALL_OBSERVABLES,
+  TECHNOLOGY_OBSERVABLES,
+  BIOLOGICS_OBSERVABLES,
+  ASSESSMENT_LEVELS
+} from "@disclosureos/observables";
+import {
+  OCS_TAXONOMY,
+  getNode,
+  getChildren,
+  getTestableNodes,
+  ORIGIN_DOMAINS,
+  ORIGIN_DOMAIN_LABELS
+} from "@disclosureos/origins";
+function registry(args2) {
+  if (args2.flags["help"]) {
+    printUsage4();
+    return;
+  }
+  const sub = args2.subcommand;
+  switch (sub) {
+    case "fields":
+      registryFields(args2);
+      break;
+    case "observables":
+      registryObservables(args2);
+      break;
+    case "origins":
+      registryOrigins(args2);
+      break;
+    default:
+      printUsage4();
+  }
+}
+function registryFields(args2) {
+  const group = args2.flags["category"];
+  const paths = deriveFieldPaths();
+  const groups = /* @__PURE__ */ new Map();
+  for (const field of paths) {
+    const top = field.path.split(".")[0] ?? field.path;
+    const list = groups.get(top) ?? [];
+    list.push(field);
+    groups.set(top, list);
+  }
+  console.log(heading("Observation Field Registry (schema-derived)"));
+  if (group) {
+    const fields = groups.get(group);
+    if (!fields || fields.length === 0) {
+      console.log(`
+  No fields found for group "${group}"`);
+      return;
+    }
+    console.log(`
+  Group: ${group}
+`);
+    const rows = fields.map((f) => [f.path, f.required ? "required" : "optional"]);
+    console.log(table(rows));
+  } else {
+    for (const groupName of [...groups.keys()].sort()) {
+      const fields = groups.get(groupName);
+      console.log(`
+  ${groupName} (${fields.length} fields)`);
+      for (const f of fields) {
+        console.log(bullet(`${f.path}${f.required ? " [required]" : ""}`));
+      }
+    }
+  }
+  console.log(`
+  ${dim(`Total: ${paths.length} schema-derived field paths`)}
+`);
+}
+function registryObservables(args2) {
+  const biologicsOnly = !!args2.flags["biologics"];
+  const techOnly = !!args2.flags["technology"];
+  console.log(heading("Observable Registry"));
+  if (!biologicsOnly) {
+    console.log(`
+  Technology Observables (AATIP-derived)
+`);
+    const techObs = Object.values(TECHNOLOGY_OBSERVABLES);
+    for (const obs of techObs) {
+      console.log(`  ${obs.code}  ${obs.label}`);
+      if (obs.description) {
+        console.log(`       ${dim(obs.description)}`);
+      }
+    }
+  }
+  if (!techOnly) {
+    console.log(`
+  Biologics Observables (NHI Detection)
+`);
+    const bioObs = Object.values(BIOLOGICS_OBSERVABLES);
+    for (const obs of bioObs) {
+      console.log(`  ${obs.code}  ${obs.label}`);
+      if (obs.description) {
+        console.log(`       ${dim(obs.description)}`);
+      }
+    }
+  }
+  console.log(`
+  ${dim(`Assessment Levels: ${ASSESSMENT_LEVELS.join(" \u2192 ")}`)}`);
+  console.log(`  ${dim(`Total: ${ALL_OBSERVABLES.length} observables`)}
+`);
+}
+function registryOrigins(args2) {
+  const targetId = args2.flags["id"];
+  const testableOnly = !!args2.flags["testable"];
+  console.log(heading("Origin Classification System (OCS)"));
+  if (testableOnly) {
+    const testable = getTestableNodes();
+    console.log(`
+  Scientifically Testable Hypotheses (${testable.length}):
+`);
+    for (const node of testable) {
+      console.log(`  [${node.id}]  ${node.label}`);
+    }
+    console.log("");
+    return;
+  }
+  if (targetId) {
+    const node = getNode(targetId);
+    if (!node) {
+      console.log(`
+  Unknown OCS node: "${targetId}"
+`);
+      return;
+    }
+    console.log(`
+${label("ID", node.id)}`);
+    console.log(label("Label", node.label));
+    console.log(label("Domain", node.domain));
+    console.log(label("Depth", String(node.depth)));
+    console.log(label("Testable", node.scientificallyTestable ? "Yes" : "No"));
+    if (node.description) {
+      console.log(label("Description", node.description));
+    }
+    if (node.aliases && node.aliases.length > 0) {
+      console.log(label("Aliases", node.aliases.join(", ")));
+    }
+    const children = getChildren(targetId);
+    if (children.length > 0) {
+      console.log(`
+  Children (${children.length}):`);
+      for (const child of children) {
+        console.log(bullet(`[${child.id}] ${child.label}`));
+      }
+    }
+    console.log("");
+    return;
+  }
+  console.log(`
+  3 Domains, ${OCS_TAXONOMY.length} total nodes
+`);
+  for (const domain of ORIGIN_DOMAINS) {
+    const domainLabel = ORIGIN_DOMAIN_LABELS[domain];
+    const domainNode = OCS_TAXONOMY.find((n) => n.depth === 0 && n.domain === domain);
+    if (domainNode) {
+      console.log(`  [${domainNode.id}] ${domainLabel}`);
+      const subdomains = getChildren(domainNode.id);
+      for (const sub of subdomains) {
+        console.log(`    [${sub.id}] ${sub.label}`);
+        const leaves = getChildren(sub.id);
+        for (const leaf of leaves) {
+          console.log(`      ${dim(`[${leaf.id}] ${leaf.label}`)}`);
+        }
+      }
+    }
+  }
+  console.log("");
+}
+function printUsage4() {
+  console.log(heading(`${BRAND} registry`));
+  console.log(`
+Introspect DisclosureOS field, observable, and origin registries.
+`);
+  console.log(`${dim("Usage:")}`);
+  console.log(`  disclosureos registry <subcommand> [options]
+`);
+  console.log(`${dim("Subcommands:")}`);
+  console.log(`  fields                     List observation field definitions`);
+  console.log(`  fields --category <cat>    Filter by category`);
+  console.log(`  observables                List all 12 observables`);
+  console.log(`  observables --biologics    Biologics only`);
+  console.log(`  observables --technology   Technology only`);
+  console.log(`  origins                    Show OCS taxonomy overview`);
+  console.log(`  origins --id <nodeId>      Show subtree for specific node`);
+  console.log(`  origins --testable         Only scientifically testable nodes
+`);
+  console.log(`${dim("Options:")}`);
+  console.log(`  --help, -h                 Show this help message
+`);
+}
+
+// src/commands/info.ts
+import { deriveFieldPaths as deriveFieldPaths2 } from "@disclosureos/scoring";
+import {
+  ALL_OBSERVABLES as ALL_OBSERVABLES2,
+  ALL_OBSERVABLE_IDS,
+  ASSESSMENT_LEVELS as ASSESSMENT_LEVELS2
+} from "@disclosureos/observables";
+import {
+  OCS_TAXONOMY as OCS_TAXONOMY2,
+  getNode as getNode2,
+  getChildren as getChildren2,
+  getAncestors,
+  ORIGIN_DOMAINS as ORIGIN_DOMAINS2
+} from "@disclosureos/origins";
+var FIELD_PATH_COUNT = deriveFieldPaths2().length;
+function info(args2) {
+  if (args2.flags["help"]) {
+    printUsage5();
+    return;
+  }
+  const sub = args2.subcommand;
+  switch (sub) {
+    case "":
+    case void 0:
+      infoOverview();
+      break;
+    case "observation":
+      infoObservation();
+      break;
+    case "observable":
+      infoObservable(args2.positional[0]);
+      break;
+    case "origin":
+      infoOrigin(args2.positional[0]);
+      break;
+    default:
+      infoOverview();
+  }
+}
+function infoOverview() {
+  console.log(heading(`${BRAND} Ecosystem`));
+  console.log(`
+  A structured data framework for UAP research.
+`);
+  console.log(table([
+    ["@disclosureos/records", `Data dictionary \u2014 ${FIELD_PATH_COUNT} schema fields, Observation type`],
+    ["@disclosureos/observables", `Detection criteria \u2014 ${ALL_OBSERVABLE_IDS.length} observables`],
+    ["@disclosureos/origins", `Classification taxonomy \u2014 ${OCS_TAXONOMY2.length} OCS nodes`],
+    ["@disclosureos/scoring", "Reference completeness + compellingness scoring"],
+    ["@disclosureos/cli", "Developer tooling (this package)"]
+  ]));
+  console.log(`
+${dim("  Commands: scaffold, validate, registry, info")}
+`);
+}
+function infoObservation() {
+  console.log(heading("Observation Type"));
+  console.log(`
+  The core record type for UAP/UAI research data.
+`);
+  console.log(`  ${dim("Required Fields:")}`);
+  console.log(bullet("id \u2014 Unique identifier"));
+  console.log(bullet("temporal \u2014 Date, time, duration"));
+  console.log(bullet("location \u2014 Coordinates, site type"));
+  console.log(bullet("status \u2014 Publication status (draft/review/published/archived/retracted)"));
+  console.log(bullet("createdAt \u2014 ISO timestamp"));
+  console.log(bullet("updatedAt \u2014 ISO timestamp"));
+  console.log(`
+  ${dim("Extension Slots:")}`);
+  console.log(bullet("observableAssessments \u2014 Technology + Biologics assessment levels"));
+  console.log(bullet("origin \u2014 OCS hypothesis assignment"));
+  console.log(`
+  ${dim("Records-owned slots: provenance, identifiers, testimony, physicalEvidence, documents")}`);
+  console.log(`  ${dim(`Total schema-derived field paths: ${FIELD_PATH_COUNT}`)}
+`);
+}
+function infoObservable(id) {
+  if (!id) {
+    console.log(heading("Observables"));
+    console.log(`
+  Use: disclosureos info observable <code>
+`);
+    console.log(`  ${dim("Available codes:")}`);
+    for (const obs2 of ALL_OBSERVABLES2) {
+      console.log(bullet(`${obs2.code} \u2014 ${obs2.label}`));
+    }
+    console.log("");
+    return;
+  }
+  const obs = ALL_OBSERVABLES2.find((o) => o.code === id || o.id === id);
+  if (!obs) {
+    console.log(`
+  Unknown observable: "${id}"`);
+    console.log(`  ${dim(`Available: ${ALL_OBSERVABLES2.map((o) => o.code).join(", ")}`)}
+`);
+    return;
+  }
+  console.log(heading(`Observable: ${obs.label}`));
+  console.log(`
+${label("Code", obs.code)}`);
+  console.log(label("ID", obs.id));
+  console.log(label("Category", obs.category));
+  if (obs.description) {
+    console.log(label("Description", obs.description));
+  }
+  console.log(`
+  ${dim("Assessment Levels:")}`);
+  for (const level of ASSESSMENT_LEVELS2) {
+    console.log(bullet(level));
+  }
+  console.log("");
+}
+function infoOrigin(id) {
+  if (!id) {
+    console.log(heading("Origin Classification System"));
+    console.log(`
+  Use: disclosureos info origin <nodeId>
+`);
+    console.log(`  ${dim("Domains:")}`);
+    for (const domain of ORIGIN_DOMAINS2) {
+      const domainNode = OCS_TAXONOMY2.find((n) => n.depth === 0 && n.domain === domain);
+      if (domainNode) {
+        console.log(bullet(`[${domainNode.id}] \u2014 ${domainNode.label}`));
+      }
+    }
+    console.log("");
+    return;
+  }
+  const node = getNode2(id);
+  if (!node) {
+    console.log(`
+  Unknown OCS node: "${id}"
+`);
+    return;
+  }
+  console.log(heading(`Origin: ${node.label}`));
+  console.log(`
+${label("ID", node.id)}`);
+  console.log(label("Label", node.label));
+  console.log(label("Domain", node.domain));
+  console.log(label("Depth", String(node.depth)));
+  console.log(label("Testable", node.scientificallyTestable ? "Yes" : "No"));
+  if (node.description) {
+    console.log(label("Description", node.description));
+  }
+  if (node.aliases && node.aliases.length > 0) {
+    console.log(label("Aliases", node.aliases.join(", ")));
+  }
+  const ancestors = getAncestors(id);
+  if (ancestors.length > 0) {
+    console.log(`
+  ${dim("Path:")}`);
+    console.log(`  ${ancestors.map((a) => a.label).join(" \u2192 ")} \u2192 ${node.label}`);
+  }
+  const children = getChildren2(id);
+  if (children.length > 0) {
+    console.log(`
+  ${dim(`Children (${children.length}):`)}`);
+    for (const child of children) {
+      console.log(bullet(`[${child.id}] ${child.label}`));
+    }
+  }
+  console.log("");
+}
+function printUsage5() {
+  console.log(heading(`${BRAND} info`));
+  console.log(`
+Quick reference for DisclosureOS types and definitions.
+`);
+  console.log(`${dim("Usage:")}`);
+  console.log(`  disclosureos info [topic] [id]
+`);
+  console.log(`${dim("Topics:")}`);
+  console.log(`  (none)               Ecosystem overview`);
+  console.log(`  observation          Observation type summary`);
+  console.log(`  observable <code>    Observable detail (e.g. TO-3, BO-1)`);
+  console.log(`  origin <nodeId>      OCS node detail (e.g. 1.1.3)
+`);
+  console.log(`${dim("Options:")}`);
+  console.log(`  --help, -h           Show this help message
+`);
+}
+
+// src/index.ts
+var CLI_VERSION = readCliVersion();
+var args = parseArgs(process.argv);
+if (args.flags["version"]) {
+  printVersion();
+} else if (args.flags["help"] && !args.command) {
+  printHelp();
+} else {
+  switch (args.command) {
+    case "scaffold":
+      scaffold(args);
+      break;
+    case "validate":
+      validate(args);
+      break;
+    case "completeness":
+      completeness(args);
+      break;
+    case "registry":
+      registry(args);
+      break;
+    case "info":
+      info(args);
+      break;
+    case "help":
+    case "":
+      printHelp();
+      break;
+    case "version":
+      printVersion();
+      break;
+    default:
+      console.log(`Unknown command: "${args.command}"
+`);
+      printHelp();
+      process.exit(1);
+  }
+}
+function printHelp() {
+  console.log(heading(`${BRAND} CLI v${CLI_VERSION}`));
+  console.log(`
+  Developer tools for the DisclosureOS ecosystem.
+`);
+  console.log(`${dim("Commands:")}`);
+  console.log(`  scaffold       Generate typed data structure templates`);
+  console.log(`  validate       Validate observation JSON files`);
+  console.log(`  completeness   Measure how fully observations populate the schema`);
+  console.log(`  registry       Introspect field, observable, and origin registries`);
+  console.log(`  info           Quick reference for types and definitions`);
+  console.log(`  help           Show this help message`);
+  console.log(`  version        Print version
+`);
+  console.log(`${dim("Global Options:")}`);
+  console.log(`  --help, -h     Show help (for any command)`);
+  console.log(`  --version, -v  Print version
+`);
+  console.log(`${dim("Examples:")}`);
+  console.log(`  disclosureos scaffold observation --full`);
+  console.log(`  disclosureos validate ./data/ --recursive`);
+  console.log(`  disclosureos completeness ./out/ --recursive`);
+  console.log(`  disclosureos registry origins --id 1.1.3`);
+  console.log(`  disclosureos info observable TO-3
+`);
+}
+function printVersion() {
+  console.log(CLI_VERSION);
+}
+function readCliVersion() {
+  try {
+    const packagePath = join(
+      dirname(fileURLToPath(import.meta.url)),
+      "..",
+      "package.json"
+    );
+    const parsed = JSON.parse(readFileSync2(packagePath, "utf8"));
+    return typeof parsed.version === "string" ? parsed.version : "1.0.0";
+  } catch {
+    return "1.0.0";
+  }
+}