@mindflight/mindbrain-personal-studio 0.6.1 → 0.6.3

package/examples/immeuble/scripts/reset-immeuble-workspace.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Reset a clean immeuble workspace and run the canonical pipeline.
+ *
+ * Usage:
+ *   node examples/immeuble/scripts/reset-immeuble-workspace.mjs [options]
+ *
+ * Options:
+ *   --db <path>              SQLite target (default: data/immeuble.sqlite)
+ *   --keep-db                Do not delete existing file first
+ *   --with-bundle-load       After import, load bundle/immeuble.bundle.json
+ *   --with-artifact-seed     Seed answer artifacts via demo-load profile
+ *   --with-business-capabilities  Seed ghostcrab:business-capability records
+ *   --engine legacy|both     Import engine (default: legacy)
+ *   --skip-provenance-validation
+ *   --require-hybrid         Fail if hybrid-compare missing or non-zero deltas
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const immeubleRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pkgRoot = resolve(immeubleRoot, "..", "..");
+const node = process.execPath;
+const reportsDir = join(immeubleRoot, "reports");
+
+const args = process.argv.slice(2);
+const dbPath = resolve(parseFlag(args, "--db", join(pkgRoot, "data/immeuble.sqlite")));
+const engine = parseFlag(args, "--engine", "legacy");
+const keepDb = args.includes("--keep-db");
+const withBundle = args.includes("--with-bundle-load");
+const withArtifacts = args.includes("--with-artifact-seed");
+const withBusinessCapabilities = args.includes("--with-business-capabilities");
+const skipProvenance = args.includes("--skip-provenance-validation");
+const requireHybrid = args.includes("--require-hybrid");
+
+const report = {
+  ok: true,
+  db_path: dbPath,
+  steps: [],
+  started_at: new Date().toISOString()
+};
+
+try {
+  if (!keepDb && existsSync(dbPath)) {
+    rmSync(dbPath);
+    report.steps.push({ step: "delete_db", ok: true });
+  }
+  mkdirSync(dirname(dbPath), { recursive: true });
+
+  runStep("build", [join(immeubleRoot, "scripts/build-immeuble-model.mjs")]);
+
+  const importArgs = [
+    join(immeubleRoot, "scripts/run-immeuble-import.mjs"),
+    "--apply",
+    "--db", dbPath,
+    "--engine", engine,
+    "--skip-preflight",
+    "--force"
+  ];
+  if (skipProvenance) importArgs.push("--skip-provenance-validation");
+  if (engine === "both") {
+    importArgs.push("--compare-output", join(reportsDir, "hybrid-compare.json"));
+  }
+  runStep("import", importArgs);
+
+  if (withArtifacts) {
+    runStep("artifact_seed", [
+      join(pkgRoot, "bin/gcp.mjs"),
+      "load", join(immeubleRoot, "contracts/answer_artifacts.seed.jsonl"),
+      "--workspace", "immeuble"
+    ], { env: { GHOSTCRAB_SQLITE_PATH: dbPath } });
+  }
+
+  if (withBusinessCapabilities) {
+    runStep("business_capability_seed", [
+      join(pkgRoot, "bin/gcp.mjs"),
+      "load", join(immeubleRoot, "contracts/business_capabilities.seed.jsonl"),
+      "--workspace", "immeuble"
+    ], { env: { GHOSTCRAB_SQLITE_PATH: dbPath } });
+  }
+
+  if (withBundle) {
+    runStep("bundle_load", [
+      join(pkgRoot, "bin/gcp.mjs"),
+      "load", join(immeubleRoot, "bundle/immeuble.bundle.json"),
+      "--workspace", "immeuble",
+      "--reindex", "all"
+    ], { env: { GHOSTCRAB_SQLITE_PATH: dbPath } });
+  }
+
+  const verifyArgs = [
+    join(immeubleRoot, "scripts/verify-immeuble-acceptance.mjs"),
+    "--db", dbPath
+  ];
+  if (requireHybrid) verifyArgs.push("--require-hybrid");
+  if (withBundle) verifyArgs.push("--require-bundle");
+  if (withBusinessCapabilities) verifyArgs.push("--require-business-capabilities");
+  runStep("verify_acceptance", verifyArgs);
+
+  runStep("audit_projections", [join(immeubleRoot, "scripts/audit-immeuble-projections.mjs")], { optional: true });
+
+  report.finished_at = new Date().toISOString();
+  writeFileSync(join(reportsDir, "reset-immeuble-workspace.json"), JSON.stringify(report, null, 2) + "\n", "utf8");
+  console.log(JSON.stringify({ ok: true, db_path: dbPath, steps: report.steps.length }, null, 2));
+} catch (err) {
+  report.ok = false;
+  report.error = err instanceof Error ? err.message : String(err);
+  report.finished_at = new Date().toISOString();
+  writeFileSync(join(reportsDir, "reset-immeuble-workspace.json"), JSON.stringify(report, null, 2) + "\n", "utf8");
+  console.error(JSON.stringify(report, null, 2));
+  process.exit(1);
+}
+
+function runStep(name, cmdArgs, opts = {}) {
+  const env = { ...process.env, ...(opts.env ?? {}), GHOSTCRAB_SQLITE_PATH: opts.env?.GHOSTCRAB_SQLITE_PATH ?? dbPath };
+  let res = spawnSync(node, cmdArgs, { cwd: pkgRoot, env, encoding: "utf8" });
+  if (res.status !== 0 && opts.fallback) {
+    res = spawnSync(opts.fallback[0], opts.fallback.slice(1), { cwd: pkgRoot, env, encoding: "utf8" });
+  }
+  const ok = res.status === 0;
+  report.steps.push({
+    step: name,
+    ok,
+    status: res.status,
+    stderr: (res.stderr || "").slice(0, 400)
+  });
+  if (!ok && !opts.optional) {
+    throw new Error(`${name} failed: ${res.stderr || res.stdout}`);
+  }
+}
+
+function parseFlag(argv, name, defaultValue) {
+  const index = argv.indexOf(name);
+  if (index === -1) return defaultValue;
+  return argv[index + 1] ?? defaultValue;
+}

package/examples/immeuble/scripts/run-immeuble-backend.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# Launch the Immeuble backend in standalone HTTP mode for live pipelines.
+set -eu
+
+REPO_ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../../.." && pwd)"
+IMMEUBLE_ROOT="$REPO_ROOT/examples/immeuble"
+
+BACKEND_BIN="${GHOSTCRAB_BACKEND_BIN:-$REPO_ROOT/cmd/backend/zig-out/bin/ghostcrab-backend}"
+BACKEND_ADDR=":8091"
+DB_PATH="$REPO_ROOT/data/immeuble-lab.sqlite"
+WORKSPACE_NAME="immeuble"
+LOG_FILE="$IMMEUBLE_ROOT/.tmp-immeuble-backend.log"
+READY_TIMEOUT_SEC=20
+WAIT_FOR_HEALTH=1
+FOREGROUND=0
+KILL_PORT=1
+
+usage() {
+  cat <<EOF
+Usage: examples/immeuble/scripts/run-immeuble-backend.sh [options]
+
+Run ghostcrab-backend in standalone HTTP mode with an Immeuble workspace context.
+
+Options:
+  --db <path>                 SQLite file to use (default: $DB_PATH)
+  --backend-bin <path>        ghostcrab-backend binary path
+  --backend-addr <:port>      listen address (default: :8091)
+  --workspace-name <name>      value for GHOSTCRAB_WORKSPACE_NAME (default: immeuble)
+  --log-file <path>           where backend logs are written
+  --ready-timeout <sec>       health-check timeout (default: 20)
+  --foreground                keep backend attached in the current shell
+  --no-health-check           do not wait for /health
+  --no-kill-port              do not free the listen port before start
+  -h, --help                  show this help
+EOF
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+  esac
+done
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --db)
+      DB_PATH="${2:?--db requires a value}"
+      shift 2
+      ;;
+    --backend-bin)
+      BACKEND_BIN="${2:?--backend-bin requires a value}"
+      shift 2
+      ;;
+    --backend-addr)
+      BACKEND_ADDR="${2:?--backend-addr requires a value}"
+      shift 2
+      ;;
+    --workspace-name)
+      WORKSPACE_NAME="${2:?--workspace-name requires a value}"
+      shift 2
+      ;;
+    --log-file)
+      LOG_FILE="${2:?--log-file requires a value}"
+      shift 2
+      ;;
+    --ready-timeout)
+      READY_TIMEOUT_SEC="${2:?--ready-timeout requires a value}"
+      shift 2
+      ;;
+    --no-health-check)
+      WAIT_FOR_HEALTH=0
+      shift
+      ;;
+    --foreground)
+      FOREGROUND=1
+      shift
+      ;;
+    --no-kill-port)
+      KILL_PORT=0
+      shift
+      ;;
+    *)
+      echo "[immeuble-backend] unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ ! -x "$BACKEND_BIN" ]]; then
+  echo "[immeuble-backend] backend binary not found: $BACKEND_BIN" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$DB_PATH")"
+mkdir -p "$(dirname "$LOG_FILE")"
+
+BACKEND_PORT="${BACKEND_ADDR##*:}"
+BACKEND_URL="http://127.0.0.1:${BACKEND_PORT}"
+
+if (( KILL_PORT == 1 )) && command -v fuser >/dev/null 2>&1; then
+  fuser -k "${BACKEND_ADDR#:}/tcp" 2>/dev/null || true
+  sleep 0.2
+fi
+
+run_backend() {
+  env \
+    GHOSTCRAB_BACKEND_ADDR="$BACKEND_ADDR" \
+    GHOSTCRAB_SQLITE_PATH="$DB_PATH" \
+    GHOSTCRAB_WORKSPACE_NAME="$WORKSPACE_NAME" \
+    "$BACKEND_BIN"
+}
+
+if (( FOREGROUND == 1 )); then
+  echo "[immeuble-backend] starting foreground: $BACKEND_BIN -- $BACKEND_ADDR (db=$DB_PATH)"
+  if ! run_backend 2>&1 | tee "$LOG_FILE"; then
+    echo "[immeuble-backend] backend exited with failure" >&2
+    exit 1
+  fi
+  exit 0
+fi
+
+echo "[immeuble-backend] starting detached: $BACKEND_BIN -- $BACKEND_ADDR (db=$DB_PATH)"
+run_backend >"$LOG_FILE" 2>&1 &
+BACKEND_PID=$!
+
+if [[ "$WAIT_FOR_HEALTH" -ne 0 ]]; then
+  ready=0
+  for attempt in $(seq 1 200); do
+    if curl -sf "$BACKEND_URL/health" >/dev/null 2>&1; then
+      ready=1
+      break
+    fi
+    if ! kill -0 "$BACKEND_PID" 2>/dev/null; then
+      echo "[immeuble-backend] backend exited before health check" >&2
+      cat "$LOG_FILE" >&2
+      exit 1
+    fi
+    if (( READY_TIMEOUT_SEC > 0 )); then
+      # Keep legacy 0.2s cadence and enforce timeout.
+      sleep 0.2
+      if (( attempt >= READY_TIMEOUT_SEC * 5 )); then
+        break
+      fi
+    else
+      sleep 0.2
+    fi
+  done
+
+  if [[ "$ready" -ne 1 ]]; then
+    echo "[immeuble-backend] backend did not become healthy at $BACKEND_URL after ${READY_TIMEOUT_SEC}s" >&2
+    cat "$LOG_FILE" >&2
+    exit 1
+  fi
+fi
+
+echo "[immeuble-backend] started"
+echo "[immeuble-backend] BACKEND_PID=$BACKEND_PID"
+echo "[immeuble-backend] BACKEND_URL=$BACKEND_URL"
+echo "[immeuble-backend] BACKEND_DB=$DB_PATH"
+echo "[immeuble-backend] BACKEND_LOG=$LOG_FILE"

package/examples/immeuble/scripts/run-immeuble-import.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * Immeuble import scenario — plan, apply, reindex, provenance, schema prefix checks.
+ *
+ * Usage:
+ *   node examples/immeuble/scripts/run-immeuble-import.mjs [--apply] [--engine both] ...
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const immeubleRoot = resolve(fileURLToPath(import.meta.url), "..", "..");
+const pkgRoot = resolve(immeubleRoot, "..", "..");
+const gcp = join(pkgRoot, "bin", "gcp.mjs");
+const runner = join(pkgRoot, "scripts", "run-structured-import-system.mjs");
+const defaultManifest = join(immeubleRoot, "import_manifest.yaml");
+const reportsDir = join(immeubleRoot, "reports");
+
+const args = process.argv.slice(2);
+const workspaceId = parseFlag(args, "--workspace-id", "immeuble");
+const engine = parseFlag(args, "--engine", "legacy");
+const manifestPath = parseFlag(args, "--manifest", defaultManifest);
+const dbPath = parseFlag(
+  args,
+  "--db",
+  join(mkdtempSync(join(tmpdir(), "gcp-immeuble-")), "immeuble.sqlite")
+);
+const evidenceDir = parseFlag(args, "--evidence-dir", reportsDir);
+const compareOutput = parseFlag(args, "--compare-output", join(reportsDir, "hybrid-compare.json"));
+const runWithApply = args.includes("--apply");
+const runWithSkipPreflight = args.includes("--skip-preflight");
+const runWithPreflight = args.includes("--preflight");
+const runWithSkipProvenance =
+  args.includes("--skip-provenance-validation") || args.includes("--no-validate-provenance");
+const runWithForce = args.includes("--force");
+
+mkdirSync(evidenceDir, { recursive: true });
+mkdirSync(reportsDir, { recursive: true });
+
+const evidence = {
+  workspace_id: workspaceId,
+  db_path: dbPath,
+  manifest: manifestPath,
+  engine,
+  apply: runWithApply,
+  preflight: runWithSkipPreflight ? "skipped" : runWithPreflight ? "forced" : "manifest-default",
+  provenance: runWithSkipProvenance ? "skipped" : "forced",
+  phases: [],
+  ok: true
+};
+
+try {
+  const plan = runRunner(false);
+  evidence.phases.push({ step: "plan", summary: plan.summary });
+
+  if (runWithApply) {
+    const apply = runRunner(true);
+    evidence.phases.push({ step: "apply", summary: apply.summary });
+
+    const reindexArgs = ["structured-import", "reindex", "--workspace-id", workspaceId, "--scope", "all"];
+    if (runWithForce) reindexArgs.splice(1, 0, "--force");
+    const reindex = runGcp(reindexArgs, true);
+    evidence.reindex = reindex.json;
+    writeFileSync(join(reportsDir, "reindex.json"), JSON.stringify(reindex.json, null, 2) + "\n", "utf8");
+
+    const applySummary = evidence.phases.find((phase) => phase.step === "apply")?.summary;
+    const hybridReindex = applySummary?.compare?.hybrid_summary ?? null;
+    const graphProjected =
+      typeof reindex.json?.graph_projected === "number" && reindex.json.graph_projected > 0
+        ? reindex.json.graph_projected
+        : typeof hybridReindex?.graph_projected === "number"
+          ? hybridReindex.graph_projected
+          : 0;
+
+    if (graphProjected <= 0) {
+      throw new Error(`reindex.graph_projected expected > 0, got ${reindex.json?.graph_projected ?? 0}`);
+    }
+
+    if (
+      (reindex.json?.graph_projected ?? 0) <= 0 &&
+      typeof hybridReindex?.graph_projected === "number" &&
+      hybridReindex.graph_projected > 0
+    ) {
+      evidence.reindex = {
+        ...reindex.json,
+        graph_projected: hybridReindex.graph_projected,
+        facet_assignments: hybridReindex.facet_assignments ?? reindex.json?.facet_assignments ?? 0,
+        source: "hybrid-apply"
+      };
+    }
+
+    const prefixCheck = assertSchemaIdPrefix(dbPath, workspaceId);
+    evidence.schema_id_prefix_check = prefixCheck;
+    writeFileSync(join(reportsDir, "schema-id-prefix-check.json"), JSON.stringify(prefixCheck, null, 2) + "\n", "utf8");
+    if (!prefixCheck.ok) {
+      throw new Error(`schema_id prefix violations: ${JSON.stringify(prefixCheck.violations.slice(0, 5))}`);
+    }
+
+    if (!runWithSkipProvenance) {
+      const provenance = runGcp(["structured-import", "validate-provenance", "--workspace-id", workspaceId], true);
+      evidence.provenance = provenance.json;
+      if (provenance.json?.ok !== true) {
+        throw new Error(`provenance validation failed: ${JSON.stringify(provenance.json)}`);
+      }
+    }
+  }
+
+  if (engine === "both") {
+    evidence.hybrid_compare_path = compareOutput;
+  }
+
+  const reportPath = join(evidenceDir, "immeuble-import-scenario.json");
+  evidence.report_path = reportPath;
+  writeFileSync(reportPath, JSON.stringify(evidence, null, 2) + "\n", "utf8");
+  console.log(JSON.stringify({ ...evidence, ok: true }, null, 2));
+} catch (err) {
+  evidence.ok = false;
+  evidence.error = err instanceof Error ? err.message : String(err);
+  const reportPath = join(evidenceDir, "immeuble-import-scenario.json");
+  evidence.report_path = reportPath;
+  writeFileSync(reportPath, JSON.stringify(evidence, null, 2) + "\n", "utf8");
+  console.error(JSON.stringify({ ...evidence, ok: false }, null, 2));
+  process.exit(1);
+}
+
+function runRunner(includeApply) {
+  const runnerArgs = [
+    "--manifest", manifestPath,
+    "--workspace-id", workspaceId,
+    "--db", dbPath,
+    "--engine", engine
+  ];
+  if (compareOutput && engine === "both") {
+    runnerArgs.push("--compare-output", compareOutput);
+  }
+  if (runWithPreflight) runnerArgs.push("--preflight");
+  else if (runWithSkipPreflight) runnerArgs.push("--skip-preflight");
+  if (runWithSkipProvenance) runnerArgs.push("--skip-provenance-validation");
+  if (runWithForce) runnerArgs.push("--force");
+  if (includeApply) runnerArgs.push("--apply");
+
+  const res = runCommand(process.execPath, [runner, ...runnerArgs], "run-structured-import-system");
+  if (res.status !== 0) {
+    throw new Error(`${res.label} failed (${res.status}): ${res.output}`);
+  }
+  const summary = parseSummary(res.stdout);
+  assertActivity(summary, includeApply ? "apply" : "plan");
+  return { stdout: res.stdout, summary };
+}
+
+function runGcp(brainArgs, parseJson = false) {
+  const res = runCommand(process.execPath, [gcp, "brain", ...brainArgs], "gcp brain");
+  if (res.status !== 0) {
+    throw new Error(`${res.label} failed (${res.status}): ${res.output}`);
+  }
+  return { stdout: res.stdout, json: parseJson ? parseSummary(res.stdout) : null };
+}
+
+function runCommand(executable, cmdArgs, label) {
+  const direct = spawnSync(executable, cmdArgs, {
+    cwd: pkgRoot,
+    env: { ...process.env, GHOSTCRAB_SQLITE_PATH: dbPath },
+    encoding: "utf8"
+  });
+  const output = [direct.stdout || "", direct.stderr || ""].join("");
+  return { status: direct.status ?? 0, stdout: direct.stdout || "", output, label };
+}
+
+function parseSummary(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  try { return JSON.parse(text.trim()); } catch { /* continue */ }
+  const lines = text.trim().split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line.startsWith("{")) {
+      try { return JSON.parse(lines.slice(i).join("\n")); } catch { /* continue */ }
+    }
+  }
+  return null;
+}
+
+function extractKitSummary(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  if (payload.runs && typeof payload.runs === "object") {
+    const merged = {};
+    for (const run of Object.values(payload.runs)) {
+      const s = run?.summary_parsed ?? (typeof run?.summary === "string" ? parseSummary(run.summary) : run?.summary);
+      if (s && typeof s === "object") Object.assign(merged, s);
+    }
+    return Object.keys(merged).length ? merged : null;
+  }
+  return payload.project ?? payload.summary_parsed ?? (typeof payload.summary === "string" ? parseSummary(payload.summary) : payload.summary);
+}
+
+function assertActivity(summary, label) {
+  const kit = extractKitSummary(summary);
+  const total = [
+    "entities_upserted", "facets_inserted", "edges_inserted", "facet_rows", "edge_rows"
+  ].reduce((acc, key) => acc + (typeof kit?.[key] === "number" ? kit[key] : 0), 0);
+  if (total <= 0) {
+    throw new Error(`${label}: expected activity > 0, got ${JSON.stringify(kit)}`);
+  }
+}
+
+function assertSchemaIdPrefix(db, workspace) {
+  let sqlite3;
+  try {
+    sqlite3 = spawnSync("sqlite3", [db, "-json", `SELECT schema_id FROM agent_facts WHERE workspace_id='${workspace}'`], { encoding: "utf8" });
+  } catch {
+    return { ok: true, skipped: true, reason: "sqlite3 not available" };
+  }
+  if (sqlite3.status !== 0) {
+    return { ok: true, skipped: true, reason: sqlite3.stderr || "sqlite3 query failed" };
+  }
+  let rows = [];
+  try { rows = JSON.parse(sqlite3.stdout || "[]"); } catch { rows = []; }
+  const violations = rows.filter((r) => r.schema_id && !String(r.schema_id).startsWith("immeuble:"));
+  return {
+    ok: violations.length === 0,
+    checked: rows.length,
+    violations: violations.map((r) => r.schema_id)
+  };
+}
+
+function parseFlag(argv, name, defaultValue) {
+  const index = argv.indexOf(name);
+  if (index === -1) return defaultValue;
+  return argv[index + 1] ?? defaultValue;
+}