mirai-graph 1.0.0-rc.1

package/packages/cli/release-state.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const https = require("https");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const root = path.resolve(__dirname, "..", "..");
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8"
+  });
+  return {
+    status: result.status === null ? 1 : result.status,
+    stdout: (result.stdout || "").trim(),
+    stderr: (result.stderr || "").trim()
+  };
+}
+
+function getJson(url) {
+  return new Promise((resolve) => {
+    const request = https.get(url, {
+      headers: {
+        "Accept": "application/json",
+        "User-Agent": "mirai-graph-release-state"
+      }
+    }, (response) => {
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => {
+        body += chunk;
+      });
+      response.on("end", () => {
+        if (response.statusCode === 404) {
+          resolve({ status_code: 404, found: false, body: null });
+          return;
+        }
+        if ((response.statusCode || 0) >= 400) {
+          resolve({
+            status_code: response.statusCode,
+            found: false,
+            error: `http_${response.statusCode}`
+          });
+          return;
+        }
+        try {
+          resolve({
+            status_code: response.statusCode,
+            found: true,
+            body: JSON.parse(body)
+          });
+        } catch (error) {
+          resolve({
+            status_code: response.statusCode,
+            found: false,
+            error: "invalid_json"
+          });
+        }
+      });
+    });
+    request.on("error", (error) => {
+      resolve({ status_code: null, found: false, error: error.code || error.message });
+    });
+    request.setTimeout(15000, () => {
+      request.destroy();
+      resolve({ status_code: null, found: false, error: "timeout" });
+    });
+  });
+}
+
+function loadPackage() {
+  const packagePath = path.join(root, "package.json");
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  return {
+    name: packageJson.name,
+    version: packageJson.version,
+    repository: packageJson.repository && packageJson.repository.url,
+    path: "package.json"
+  };
+}
+
+function parseGitHubRepo(repositoryUrl) {
+  if (!repositoryUrl) {
+    return null;
+  }
+  const match = repositoryUrl.match(/github\.com[:/](.+?)\/(.+?)(?:\.git)?$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    owner: match[1],
+    repo: match[2].replace(/\.git$/, "")
+  };
+}
+
+async function buildState(options = {}) {
+  const pkg = loadPackage();
+  const tag = `v${pkg.version}`;
+  const requireGitTag = Boolean(options.requireGitTag || options.requireGithubRelease || options.requireNpmPublished);
+  const requireGithubRelease = Boolean(options.requireGithubRelease || options.requireNpmPublished);
+  const blockers = [];
+  const warnings = [];
+
+  const head = run("git", ["rev-parse", "HEAD"]);
+  const tagCommit = run("git", ["rev-parse", `${tag}^{}`]);
+  const status = run("git", ["status", "--short", "--branch", "--untracked-files=all"]);
+
+  const npmAuth = run("npm", ["whoami"]);
+  const npmRegistry = await getJson(`https://registry.npmjs.org/${encodeURIComponent(pkg.name)}`);
+  const npmPackage = {
+    registry_url: `https://registry.npmjs.org/${pkg.name}`,
+    found: npmRegistry.found,
+    status_code: npmRegistry.status_code,
+    latest: null,
+    version_published: false,
+    error: npmRegistry.error || null
+  };
+
+  if (npmRegistry.found && npmRegistry.body) {
+    npmPackage.latest = npmRegistry.body["dist-tags"] && npmRegistry.body["dist-tags"].latest || null;
+    npmPackage.version_published = Boolean(npmRegistry.body.versions && npmRegistry.body.versions[pkg.version]);
+  }
+
+  const npm = {
+    authenticated: npmAuth.status === 0,
+    whoami: npmAuth.status === 0 ? npmAuth.stdout : null,
+    auth_error: npmAuth.status === 0 ? null : classifyNpmAuthError(npmAuth.stderr || npmAuth.stdout),
+    package: npmPackage
+  };
+
+  if (!npm.authenticated) {
+    blockers.push({
+      id: "npm_auth_missing",
+      severity: "publish_blocker",
+      message: "npm publish requires npm login or an owner-approved npm token."
+    });
+  }
+  if (!npmPackage.version_published) {
+    blockers.push({
+      id: "npm_package_version_not_published",
+      severity: options.requireNpmPublished ? "release_blocker" : "publication_pending",
+      message: `${pkg.name}@${pkg.version} is not published on npm.`
+    });
+  }
+
+  const githubRepo = parseGitHubRepo(pkg.repository);
+  let githubRelease = {
+    repository: githubRepo,
+    tag,
+    found: false,
+    url: null,
+    draft: null,
+    prerelease: null,
+    error: githubRepo ? null : "repository_not_github"
+  };
+
+  if (githubRepo) {
+    const release = await getJson(`https://api.github.com/repos/${githubRepo.owner}/${githubRepo.repo}/releases/tags/${tag}`);
+    githubRelease = {
+      repository: githubRepo,
+      tag,
+      found: release.found,
+      status_code: release.status_code,
+      url: release.body && release.body.html_url || null,
+      name: release.body && release.body.name || null,
+      draft: release.body ? Boolean(release.body.draft) : null,
+      prerelease: release.body ? Boolean(release.body.prerelease) : null,
+      error: release.error || null
+    };
+  }
+
+  if (head.status !== 0) {
+    blockers.push({ id: "git_head_unavailable", severity: "release_blocker", message: "Cannot resolve git HEAD." });
+  }
+  if (tagCommit.status !== 0) {
+    blockers.push({
+      id: "git_tag_missing",
+      severity: requireGitTag ? "release_blocker" : "release_pending",
+      message: `Local tag ${tag} is missing.`
+    });
+  }
+  if (!githubRelease.found) {
+    blockers.push({
+      id: "github_release_missing",
+      severity: requireGithubRelease ? "release_blocker" : "release_pending",
+      message: `GitHub Release ${tag} is missing.`
+    });
+  }
+  if (status.stdout.includes("\n")) {
+    warnings.push({
+      id: "working_tree_has_changes",
+      message: "Working tree has local changes; release state is still reportable but should not be published until clean."
+    });
+  }
+
+  const fatalBlockers = blockers.filter((blocker) => blocker.severity === "release_blocker");
+  const valid = fatalBlockers.length === 0;
+
+  return {
+    report_type: "mirai_graph_release_state",
+    valid,
+    generated_at: new Date().toISOString(),
+    package: pkg,
+    git: {
+      head: head.status === 0 ? head.stdout : null,
+      tag,
+      tag_commit: tagCommit.status === 0 ? tagCommit.stdout : null,
+      tag_exists: tagCommit.status === 0,
+      status: status.stdout
+    },
+    github_release: githubRelease,
+    npm,
+    blockers,
+    warnings,
+    boundary: [
+      "This report does not publish npm packages, create tags or mutate GitHub releases.",
+      "Pre-tag release-state checks may report git tag and GitHub Release as release_pending.",
+      "Missing npm authentication is a publish blocker, not a reason to expose tokens.",
+      "A release-state report is evidence, not release authorization."
+    ]
+  };
+}
+
+function classifyNpmAuthError(output) {
+  if (output.includes("ENEEDAUTH")) {
+    return "ENEEDAUTH";
+  }
+  if (output.includes("E401")) {
+    return "E401";
+  }
+  if (output.includes("not logged in")) {
+    return "not_logged_in";
+  }
+  return "unknown";
+}
+
+function renderMarkdown(state) {
+  const lines = [];
+  lines.push("# Mirai Graph Release State");
+  lines.push("");
+  lines.push(`Generated: ${state.generated_at}`);
+  lines.push(`Valid for release-state check: \`${state.valid}\``);
+  lines.push("");
+  lines.push("## Package");
+  lines.push("");
+  lines.push(`- Name: \`${state.package.name}\``);
+  lines.push(`- Version: \`${state.package.version}\``);
+  lines.push(`- Repository: \`${state.package.repository}\``);
+  lines.push("");
+  lines.push("## Git");
+  lines.push("");
+  lines.push(`- HEAD: \`${state.git.head || "unavailable"}\``);
+  lines.push(`- Tag: \`${state.git.tag}\``);
+  lines.push(`- Tag exists: \`${state.git.tag_exists}\``);
+  lines.push("");
+  lines.push("## GitHub Release");
+  lines.push("");
+  lines.push(`- Found: \`${state.github_release.found}\``);
+  lines.push(`- URL: ${state.github_release.url || "n/a"}`);
+  lines.push(`- Draft: \`${state.github_release.draft}\``);
+  lines.push(`- Prerelease: \`${state.github_release.prerelease}\``);
+  lines.push("");
+  lines.push("## NPM Package");
+  lines.push("");
+  lines.push(`- Registry found: \`${state.npm.package.found}\``);
+  lines.push(`- Version published: \`${state.npm.package.version_published}\``);
+  lines.push(`- Latest: \`${state.npm.package.latest || "n/a"}\``);
+  lines.push(`- Authenticated: \`${state.npm.authenticated}\``);
+  lines.push(`- Auth error: \`${state.npm.auth_error || "n/a"}\``);
+  lines.push("");
+  lines.push("## Blockers");
+  lines.push("");
+  if (state.blockers.length === 0) {
+    lines.push("- None.");
+  } else {
+    for (const blocker of state.blockers) {
+      lines.push(`- \`${blocker.id}\` (${blocker.severity}): ${blocker.message}`);
+    }
+  }
+  lines.push("");
+  lines.push("## Warnings");
+  lines.push("");
+  if (state.warnings.length === 0) {
+    lines.push("- None.");
+  } else {
+    for (const warning of state.warnings) {
+      lines.push(`- \`${warning.id}\`: ${warning.message}`);
+    }
+  }
+  lines.push("");
+  lines.push("## Boundary");
+  lines.push("");
+  for (const item of state.boundary) {
+    lines.push(`- ${item}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const markdown = args.includes("--markdown");
+  const requireNpmPublished = args.includes("--require-npm-published");
+  const requireGitTag = args.includes("--require-git-tag");
+  const requireGithubRelease = args.includes("--require-github-release");
+  const state = await buildState({ requireNpmPublished, requireGitTag, requireGithubRelease });
+  if (markdown) {
+    process.stdout.write(renderMarkdown(state));
+  } else {
+    process.stdout.write(`${JSON.stringify(state, null, 2)}\n`);
+  }
+  if (!state.valid || (requireNpmPublished && !state.npm.package.version_published)) {
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  buildState,
+  renderMarkdown
+};

package/packages/cli/seed-preview.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+function usage() {
+  console.error("Usage: node packages/cli/seed-preview.js <seed-file> [--write <output-file>]");
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function titleFromFamily(family) {
+  return family
+    .split("_")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function buildEmbryo(seed) {
+  const maxObjects = Math.max(1, Math.min(seed.growth_rules.max_initial_objects || 1, 8));
+  const families = (seed.growth_rules.allowed_object_families || []).slice(0, maxObjects);
+  const profile = seed.target_profile.replace(/^profile\./, "");
+  const candidateObjects = families.map((family, index) => ({
+    id: `${family}.candidate_${index + 1}`,
+    kind: family,
+    title: `Candidate ${titleFromFamily(family)}`,
+    summary: `Candidate ${family} object proposed from seed ${seed.seed_id}.`,
+    readiness: "draft",
+    evidence: [],
+    profile
+  }));
+
+  return {
+    schema_version: "0.1.0",
+    embryo_id: `embryo.${seed.seed_id.replace(/^seed\./, "")}`,
+    seed_id: seed.seed_id,
+    generated_at: new Date().toISOString(),
+    candidate_objects: candidateObjects,
+    candidate_relations: [],
+    uncertain_items: [
+      "This is a deterministic seed preview, not extracted canonical graph state."
+    ],
+    review_questions: [
+      "Do the candidate object families match the graph purpose?",
+      "Are source boundaries sufficient for the first extraction pass?",
+      "Should canonical write remain blocked until human review?"
+    ],
+    stop_conditions_triggered: []
+  };
+}
+
+const seedPath = process.argv[2];
+const writeFlagIndex = process.argv.indexOf("--write");
+const outputPath = writeFlagIndex >= 0 ? process.argv[writeFlagIndex + 1] : null;
+
+if (!seedPath || (writeFlagIndex >= 0 && !outputPath)) {
+  usage();
+  process.exit(2);
+}
+
+try {
+  const seed = readJson(path.resolve(seedPath));
+  const embryo = buildEmbryo(seed);
+  const output = JSON.stringify(embryo, null, 2);
+
+  if (outputPath) {
+    const resolvedOutputPath = path.resolve(outputPath);
+    fs.mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
+    fs.writeFileSync(resolvedOutputPath, `${output}\n`);
+  }
+
+  console.log(output);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/packages/cli/validate-adopter-workflow.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+const node = process.execPath;
+const cli = path.join(root, "packages", "cli", "mirai-graph.js");
+
+const checks = [
+  {
+    name: "profile map",
+    args: ["choose-profile"],
+    includes: ["Mirai Graph Profile Selection", "software_specification", "organization_governance"]
+  },
+  {
+    name: "developer plan",
+    args: ["adopter", "plan", "developer"],
+    includes: ["Mirai Graph Adopter Plan: developer", "software-project-starter", "launch/evidence/kaizen"]
+  },
+  {
+    name: "ai employee plan",
+    args: ["adopter", "plan", "ai_employee"],
+    includes: ["Mirai Graph Adopter Plan: ai-employee", "ai_employee", "ai-employee-starter"]
+  },
+  {
+    name: "organization report",
+    args: ["adopter", "report", "templates/organization-governance-starter"],
+    includes: ["Mirai Graph Adopter Report", "organization_governance", "Adoption Checklist"]
+  }
+];
+
+const errors = [];
+
+for (const check of checks) {
+  const result = spawnSync(node, [cli, ...check.args], {
+    cwd: root,
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    errors.push(`${check.name}: command failed with exit ${result.status}`);
+    continue;
+  }
+  const output = `${result.stdout}\n${result.stderr}`;
+  for (const expected of check.includes) {
+    if (!output.includes(expected)) {
+      errors.push(`${check.name}: missing expected text ${JSON.stringify(expected)}`);
+    }
+  }
+}
+
+const result = {
+  mode: "adopter_workflow",
+  valid: errors.length === 0,
+  checked_commands: checks.map((check) => `mirai-graph ${check.args.join(" ")}`),
+  errors
+};
+
+console.log(JSON.stringify(result, null, 2));
+
+if (errors.length > 0) {
+  process.exit(1);
+}

package/packages/cli/validate-baseline-comparison.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+
+const resultPath = process.argv[2] || "benchmarks/synthetic-context-reduction-v0/results/baseline-comparison-result.json";
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function requireString(value, label, errors) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${label} must be a non-empty string`);
+  }
+}
+
+function requireNumber(value, label, errors) {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    errors.push(`${label} must be a number`);
+  }
+}
+
+const errors = [];
+const result = readJson(resultPath);
+
+requireString(result.schema_version, "schema_version", errors);
+requireString(result.id, "id", errors);
+requireString(result.task_id, "task_id", errors);
+if (result.public_safety !== "synthetic_public") {
+  errors.push("public_safety must be synthetic_public");
+}
+if (result.comparison_type !== "baseline_vs_mirai_graph") {
+  errors.push("comparison_type must be baseline_vs_mirai_graph");
+}
+
+for (const side of ["baseline", "mirai_graph"]) {
+  const metrics = result[side];
+  if (!metrics || typeof metrics !== "object" || Array.isArray(metrics)) {
+    errors.push(`${side} must be an object`);
+    continue;
+  }
+  for (const field of [
+    "context_units",
+    "missed_dependencies",
+    "unsupported_assumptions",
+    "evidence_coverage_percent",
+    "false_progress_claims"
+  ]) {
+    requireNumber(metrics[field], `${side}.${field}`, errors);
+  }
+}
+
+if (!result.outcome || typeof result.outcome !== "object" || Array.isArray(result.outcome)) {
+  errors.push("outcome must be an object");
+} else {
+  requireNumber(result.outcome.context_reduction_percent, "outcome.context_reduction_percent", errors);
+  if (!Array.isArray(result.outcome.improved_metrics) || result.outcome.improved_metrics.length === 0) {
+    errors.push("outcome.improved_metrics must be a non-empty array");
+  }
+  if (!Array.isArray(result.outcome.regressed_metrics)) {
+    errors.push("outcome.regressed_metrics must be an array");
+  }
+  requireString(result.outcome.verdict, "outcome.verdict", errors);
+}
+
+if (
+  result.baseline &&
+  result.mirai_graph &&
+  typeof result.baseline.context_units === "number" &&
+  typeof result.mirai_graph.context_units === "number" &&
+  result.mirai_graph.context_units > result.baseline.context_units
+) {
+  errors.push("mirai_graph.context_units must not exceed baseline.context_units for this fixture");
+}
+
+if (
+  result.baseline &&
+  result.mirai_graph &&
+  typeof result.mirai_graph.evidence_coverage_percent === "number" &&
+  typeof result.baseline.evidence_coverage_percent === "number" &&
+  result.mirai_graph.evidence_coverage_percent < result.baseline.evidence_coverage_percent
+) {
+  errors.push("mirai_graph.evidence_coverage_percent must not be lower than baseline for this fixture");
+}
+
+if (!Array.isArray(result.limitations) || result.limitations.length === 0) {
+  errors.push("limitations must be a non-empty array");
+}
+
+if (
+  typeof result.claim_boundary !== "string" ||
+  !result.claim_boundary.toLowerCase().includes("synthetic")
+) {
+  errors.push("claim_boundary must explicitly keep the claim synthetic");
+}
+
+const output = {
+  mode: "baseline_comparison_result",
+  target: resultPath,
+  valid: errors.length === 0,
+  errors
+};
+
+console.log(JSON.stringify(output, null, 2));
+process.exit(output.valid ? 0 : 1);