jishushell 0.6.5 → 0.6.18

package/scripts/check-integration-isolation.ts

@@ -0,0 +1,541 @@
+#!/usr/bin/env -S node --experimental-strip-types
+/**
+ * check-integration-isolation — AppIntegration isolation checks.
+ *
+ * Two invariants:
+ *
+ *   1. Core framework files never import specific integration implementation
+ *      modules such as OpenClaw/Hermes integrations or mcporter helpers.
+ *      Framework code reaches integrations only through the integration
+ *      registry/dispatch surface.
+ *
+ *   2. Fixture `instance.json` samples under
+ *      `scripts/fixtures/instances/<name>/` satisfy the minimum meta
+ *      contract: `id`, `name`, a fixture-local integration discriminator,
+ *      and (for Hermes) the required `paths.integrationHome` /
+ *      `paths.primaryConfig` / `paths.secretEnv` entries. Legacy fixtures whose
+ *      name starts with
+ *      `legacy-openclaw` must still resolve to integration kind `openclaw`
+ *      through historical markers such as `openclaw_home`. This check is
+ *      intentionally self-contained: runtime code no longer exposes a
+ *      legacy marker classifier.
+ *
+ * Run via `npm run check:contracts`. Exits non-zero on violation.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+const REPO_ROOT = resolve(import.meta.dirname ?? ".", "..");
+
+/**
+ * Files that must not import any specific integration directly. This keeps
+ * generic framework code from depending on OpenClaw/Hermes implementation
+ * details during migration toward docs/core-app-architecture.md.
+ */
+const CORE_FILES = [
+  "src/services/app-common/execution-owner.ts",
+  "src/services/app-common/integration-refs.ts",
+  "src/services/instances/manager.ts",
+  "src/services/runtime/drivers/nomad.ts",
+  "src/services/setup/setup-manager.ts",
+  "src/services/backup/backup-manager.ts",
+  "src/services/connections/apply.ts",
+  "src/services/connections/transactor.ts",
+  "src/services/llm-proxy/index.ts",
+  "src/routes/instances.ts",
+  "src/routes/setup.ts",
+  "src/server.ts",
+] as const;
+
+/**
+ * Regexes for forbidden integration implementation imports. Covers both
+ * static imports and dynamic `import()`. Per-integration route modules are
+ * not blocked here: they are HTTP registration surfaces, not workload/runtime
+ * implementation details.
+ */
+const FORBIDDEN_IMPORT_PATTERNS = [
+  /from\s+["'][^"']*\/integrations\/(?:openclaw|hermes|custom)\/(?:integration|mcporter)(?:\.[jt]s)?["']/g,
+  /import\s*\(\s*["'][^"']*\/integrations\/(?:openclaw|hermes|custom)\/(?:integration|mcporter)(?:\.[jt]s)?["']\s*\)/g,
+];
+
+const CONNECTION_TRANSACTOR_PRIVATE_LAYOUT_PATTERNS: Array<{
+  pattern: RegExp;
+  description: string;
+}> = [
+  { pattern: /openclaw-home|openclaw\.json|mcporter\.json/i, description: "OpenClaw private layout" },
+  { pattern: /agent-home|config\.yaml/i, description: "Hermes private layout" },
+];
+
+const INSTANCE_ROUTE_PRIVATE_SURFACE_PATTERNS: Array<{
+  pattern: RegExp;
+  description: string;
+}> = [
+  {
+    pattern: /browserless|browser-allowlist|browser-allow-all|browser-policy/i,
+    description: "Browserless/OpenClaw browser routes belong in their owning integration/app route module",
+  },
+];
+
+const FORBIDDEN_PATHS: Array<{ path: string; rule: string }> = [
+  {
+    path: "src/services/integrations/browserless",
+    rule: "Browserless is a plain AppSpec app; app-owned HTTP code belongs under src/services/app-modules/browserless",
+  },
+  {
+    path: "src/services/integrations/browser-policy.ts",
+    rule: "Browser policy is capability-level shared behavior; keep it under src/services/capabilities/browser-policy.ts",
+  },
+];
+
+const APP_MODULES_ROOT = "src/services/app-modules";
+const APP_MODULE_FORBIDDEN_IMPORT_PATTERNS = [
+  /from\s+["'][^"']*\/integrations\/(?:openclaw|hermes|anythingllm|jishukb|custom|installable)\/[^"']+["']/g,
+  /import\s*\(\s*["'][^"']*\/integrations\/(?:openclaw|hermes|anythingllm|jishukb|custom|installable)\/[^"']+["']\s*\)/g,
+];
+
+const APP_MODULE_FILE_PATTERNS: Array<{ file: string; pattern: RegExp; rule: string }> = [
+  {
+    file: "src/services/app-modules/browserless/routes.ts",
+    pattern: /\.openclaw\/agents\/main\/sessions\/sessions\.json/,
+    rule: "browserless-private-openclaw-path: Browserless route must not hardcode OpenClaw private session paths",
+  },
+  {
+    file: "src/services/app-modules/browserless/routes.ts",
+    pattern: /getIntegration\(\s*["']openclaw["']\s*\)/,
+    rule: "browserless-fixed-consumer-kind: Browserless route must not branch on a fixed OpenClaw integration kind",
+  },
+];
+
+/**
+ * Literal strings that indicate kind-specific bleed-through into
+ * framework files. These are advisory only for now: existing OpenClaw
+ * legacy code may still contain OPENCLAW_HOME env references etc. We log
+ * them but don't fail the build — the physical migration cleans them up
+ * in a follow-up PR. When MIGRATION_STRICT=1 is set, they become errors.
+ */
+const KIND_LITERAL_PATTERNS: Array<{ pattern: RegExp; description: string }> = [
+  {
+    pattern: /JOB_PREFIX\s*=\s*["']openclaw-/,
+    description: `JOB_PREFIX literal "openclaw-" — use integration.nomadJobPrefix`,
+  },
+  {
+    pattern: /OPENCLAW_HOME|OPENCLAW_INSTANCE_ID|OPENCLAW_GATEWAY_PORT/,
+    description: `OpenClaw-specific env var literal — should live in OpenClawIntegration`,
+  },
+  {
+    pattern: /isHermesInstance\s*\(/,
+    description: `isHermesInstance() — runtime-specific branch, should dispatch via getIntegration`,
+  },
+  {
+    pattern: /agentType\s*===\s*["']hermes["']|agentType\s*===\s*["']openclaw["']/,
+    description: `agentType literal comparison — dispatch through integration metadata instead`,
+  },
+];
+
+const STRICT = process.env.MIGRATION_STRICT === "1";
+
+type Violation = {
+  file: string;
+  line: number;
+  column: number;
+  text: string;
+  rule: string;
+};
+
+function isCommentLine(lineText: string): boolean {
+  const t = lineText.trimStart();
+  return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+}
+
+function findViolations(filepath: string, content: string): Violation[] {
+  const violations: Violation[] = [];
+
+  // 1. Forbidden integration implementation imports (HARD errors)
+  for (const pattern of FORBIDDEN_IMPORT_PATTERNS) {
+    let match: RegExpExecArray | null;
+    const re = new RegExp(pattern.source, "g");
+    while ((match = re.exec(content)) !== null) {
+      const before = content.slice(0, match.index);
+      const line = before.split("\n").length;
+      const column = match.index - before.lastIndexOf("\n");
+      violations.push({
+        file: filepath,
+        line,
+        column,
+        text: match[0],
+        rule: "integration-import-forbidden",
+      });
+    }
+  }
+
+  if (filepath === "src/services/connections/transactor.ts") {
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      for (const { pattern, description } of CONNECTION_TRANSACTOR_PRIVATE_LAYOUT_PATTERNS) {
+        if (!pattern.test(lines[i])) continue;
+        violations.push({
+          file: filepath,
+          line: i + 1,
+          column: 1,
+          text: lines[i].trim().slice(0, 120),
+          rule: `connection-private-layout: ${description} belongs in its integration hook`,
+        });
+      }
+    }
+  }
+
+  if (filepath === "src/routes/instances.ts") {
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const lineText = lines[i];
+      if (isCommentLine(lineText)) continue;
+      for (const { pattern, description } of INSTANCE_ROUTE_PRIVATE_SURFACE_PATTERNS) {
+        if (!pattern.test(lineText)) continue;
+        violations.push({
+          file: filepath,
+          line: i + 1,
+          column: 1,
+          text: lineText.trim().slice(0, 120),
+          rule: `instance-route-private-surface: ${description}`,
+        });
+      }
+    }
+  }
+
+  // 2. Kind-specific literals (SOFT warnings unless MIGRATION_STRICT=1).
+  //    Comment lines are skipped because docstrings are not actual code
+  //    bleed-through.
+  if (STRICT) {
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const lineText = lines[i];
+      if (isCommentLine(lineText)) continue;
+      for (const { pattern, description } of KIND_LITERAL_PATTERNS) {
+        if (pattern.test(lineText)) {
+          violations.push({
+            file: filepath,
+            line: i + 1,
+            column: 1,
+            text: lineText.trim().slice(0, 120),
+            rule: `kind-literal: ${description}`,
+          });
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+function walkFiles(relRoot: string): string[] {
+  const absRoot = resolve(REPO_ROOT, relRoot);
+  const out: string[] = [];
+  const visit = (relDir: string): void => {
+    const absDir = resolve(REPO_ROOT, relDir);
+    let entries: string[];
+    try {
+      entries = readdirSync(absDir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const relPath = resolve(absDir, entry).replace(`${REPO_ROOT}/`, "");
+      try {
+        const stats = statSync(resolve(REPO_ROOT, relPath));
+        if (stats.isDirectory()) {
+          visit(relPath);
+          continue;
+        }
+        if (stats.isFile()) out.push(relPath);
+      } catch {
+        continue;
+      }
+    }
+  };
+  try {
+    if (!statSync(absRoot).isDirectory()) return [];
+  } catch {
+    return [];
+  }
+  visit(relRoot);
+  return out;
+}
+
+// ── Fixture schema checks (plan §30.3) ───────────────────────────────
+//
+// Keep the schema rules inline: we only validate a handful of fields and
+// pulling in ajv for a single static script adds disproportionate churn.
+// Keep the historical fixture classifier inline:
+//   - every meta must carry `id` / `name`
+//   - declared `integrations[].kind` wins; otherwise fixture checks fall
+//     back to legacy markers (openclaw_home, hermes_home, app_type, ...)
+//   - Hermes fixtures must declare `paths.integrationHome` +
+//     `paths.primaryConfig`
+//   - fixtures named `legacy-openclaw*` must still resolve to
+//     integration kind `openclaw` via a legacy marker.
+
+type FixtureViolation = { fixture: string; rule: string; detail: string };
+
+function nonEmpty(v: unknown): string {
+  return typeof v === "string" ? v.trim() : "";
+}
+
+function runtimeEnv(meta: Record<string, unknown>): Record<string, unknown> {
+  const env = (meta.runtime as Record<string, unknown> | undefined)?.env;
+  return env && typeof env === "object" && !Array.isArray(env)
+    ? (env as Record<string, unknown>)
+    : {};
+}
+
+/**
+ * Self-contained classifier for historical fixture samples. Runtime code
+ * must not depend on these legacy markers after Step 13.
+ */
+function resolveFixtureIntegrationKind(meta: Record<string, unknown>): string | null {
+  const canonical = nonEmpty(((meta.integrations as Array<Record<string, unknown>> | undefined)?.[0])?.kind);
+  if (canonical) return canonical;
+  const derived = nonEmpty(meta.integrationKind);
+  if (derived) return derived;
+  const declared = nonEmpty(meta.agentType);
+  if (declared) return declared;
+
+  const appType = nonEmpty(meta.app_type);
+  if (appType === "hermes-agent") return "hermes";
+  if (appType === "custom") return "custom";
+  if (appType === "openclaw") return "openclaw";
+  if (appType === "ollama") return null;
+
+  const env = runtimeEnv(meta);
+  if (nonEmpty(meta.ollama_home) || nonEmpty(env.OLLAMA_HOST) || nonEmpty(env.OLLAMA_MODELS)) {
+    return null;
+  }
+  if (nonEmpty(meta.app_spec_ref)) return "custom";
+  if (meta.definition && !meta.agent) return "custom";
+  if (
+    nonEmpty(meta.hermes_home)
+    || nonEmpty(meta.hermes_env_file)
+    || nonEmpty(env.HERMES_HOME)
+    || nonEmpty(env.HERMES_WEBUI_PORT)
+    || nonEmpty(env.JISHUSHELL_HERMES_SOURCE_REF)
+  ) return "hermes";
+  if (
+    nonEmpty(meta.openclaw_home)
+    || nonEmpty(env.OPENCLAW_HOME)
+    || nonEmpty(env.OPENCLAW_CONFIG_PATH)
+    || nonEmpty(env.OPENCLAW_GATEWAY_PORT)
+  ) return "openclaw";
+  return null;
+}
+
+function checkFixture(fixtureName: string, meta: Record<string, unknown>): FixtureViolation[] {
+  const out: FixtureViolation[] = [];
+  const integrationKind = resolveFixtureIntegrationKind(meta);
+  if (typeof meta.id !== "string" || !meta.id) {
+    out.push({ fixture: fixtureName, rule: "missing-id", detail: "instance.json must carry a non-empty string id" });
+  }
+  if (typeof meta.name !== "string" || !meta.name) {
+    out.push({ fixture: fixtureName, rule: "missing-name", detail: "instance.json must carry a non-empty string name" });
+  }
+  if (integrationKind === "hermes") {
+    const paths = (meta.paths ?? {}) as Record<string, unknown>;
+    const integrationHome = typeof paths.integrationHome === "string" && paths.integrationHome
+      ? paths.integrationHome
+      : typeof paths.agentHome === "string" && paths.agentHome
+        ? paths.agentHome
+        : "";
+    if (!integrationHome) {
+      out.push({
+        fixture: fixtureName,
+        rule: "hermes-paths-integrationHome",
+        detail: "hermes instance.json requires paths.integrationHome",
+      });
+    }
+    for (const key of ["primaryConfig", "secretEnv"] as const) {
+      if (typeof paths[key] !== "string" || !paths[key]) {
+        out.push({
+          fixture: fixtureName,
+          rule: `hermes-paths-${key}`,
+          detail: `hermes instance.json requires paths.${key}`,
+        });
+      }
+    }
+  }
+  if (fixtureName.startsWith("legacy-openclaw") && integrationKind !== "openclaw") {
+    out.push({
+      fixture: fixtureName,
+      rule: "legacy-backfill",
+      detail: `legacy fixture must resolve to integration kind "openclaw" via legacy markers, got ${integrationKind === null ? "null" : `"${integrationKind}"`}`,
+    });
+  }
+  return out;
+}
+
+function loadFixtures(): FixtureViolation[] {
+  const fixturesRoot = resolve(REPO_ROOT, "scripts/fixtures/instances");
+  let entries: string[];
+  try {
+    entries = readdirSync(fixturesRoot);
+  } catch {
+    return []; // directory optional during early migrations
+  }
+  const violations: FixtureViolation[] = [];
+  for (const entry of entries) {
+    const fullPath = resolve(fixturesRoot, entry);
+    try {
+      if (!statSync(fullPath).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const metaPath = resolve(fullPath, "instance.json");
+    let raw: string;
+    try {
+      raw = readFileSync(metaPath, "utf-8");
+    } catch {
+      violations.push({ fixture: entry, rule: "missing-instance-json", detail: metaPath });
+      continue;
+    }
+    try {
+      const meta = JSON.parse(raw) as Record<string, unknown>;
+      violations.push(...checkFixture(entry, meta));
+    } catch (e: any) {
+      violations.push({ fixture: entry, rule: "invalid-json", detail: e?.message ?? String(e) });
+    }
+  }
+  return violations;
+}
+
+function main(): void {
+  const allViolations: Violation[] = [];
+  const softFindings: Array<{ file: string; line: number; text: string; description: string }> = [];
+
+  for (const item of FORBIDDEN_PATHS) {
+    const abs = resolve(REPO_ROOT, item.path);
+    try {
+      statSync(abs);
+      allViolations.push({
+        file: item.path,
+        line: 1,
+        column: 1,
+        text: item.path,
+        rule: `forbidden-path: ${item.rule}`,
+      });
+    } catch {
+      // Expected: forbidden path does not exist.
+    }
+  }
+
+  for (const relPath of CORE_FILES) {
+    const abs = resolve(REPO_ROOT, relPath);
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf-8");
+    } catch {
+      console.warn(`[check-integration-isolation] skip (not found): ${relPath}`);
+      continue;
+    }
+    allViolations.push(...findViolations(relPath, content));
+
+    // Collect soft findings separately so non-strict runs can still report them.
+    if (!STRICT) {
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const lineText = lines[i];
+        if (isCommentLine(lineText)) continue;
+        for (const { pattern, description } of KIND_LITERAL_PATTERNS) {
+          if (pattern.test(lineText)) {
+            softFindings.push({
+              file: relPath,
+              line: i + 1,
+              text: lineText.trim().slice(0, 120),
+              description,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  for (const relPath of walkFiles(APP_MODULES_ROOT)) {
+    if (!/\.[cm]?[jt]s$/.test(relPath)) continue;
+    let content: string;
+    try {
+      content = readFileSync(resolve(REPO_ROOT, relPath), "utf-8");
+    } catch {
+      continue;
+    }
+
+    for (const pattern of APP_MODULE_FORBIDDEN_IMPORT_PATTERNS) {
+      let match: RegExpExecArray | null;
+      const re = new RegExp(pattern.source, "g");
+      while ((match = re.exec(content)) !== null) {
+        const before = content.slice(0, match.index);
+        const line = before.split("\n").length;
+        const column = match.index - before.lastIndexOf("\n");
+        allViolations.push({
+          file: relPath,
+          line,
+          column,
+          text: match[0],
+          rule: "app-module-integration-import-forbidden",
+        });
+      }
+    }
+  }
+
+  for (const { file, pattern, rule } of APP_MODULE_FILE_PATTERNS) {
+    let content: string;
+    try {
+      content = readFileSync(resolve(REPO_ROOT, file), "utf-8");
+    } catch {
+      continue;
+    }
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      if (!pattern.test(lines[i])) continue;
+      allViolations.push({
+        file,
+        line: i + 1,
+        column: 1,
+        text: lines[i].trim().slice(0, 160),
+        rule,
+      });
+    }
+  }
+
+  const fixtureViolations = loadFixtures();
+
+  if (allViolations.length === 0 && softFindings.length === 0 && fixtureViolations.length === 0) {
+    console.log("[check-integration-isolation] OK — core files are fully decoupled from specific integrations");
+    process.exit(0);
+  }
+
+  if (allViolations.length > 0) {
+    console.error(`\n[check-integration-isolation] ${allViolations.length} HARD violation(s):\n`);
+    for (const v of allViolations) {
+      console.error(`  ${v.file}:${v.line}:${v.column}  [${v.rule}]`);
+      console.error(`    ${v.text}`);
+    }
+  }
+
+  if (fixtureViolations.length > 0) {
+    console.error(`\n[check-integration-isolation] ${fixtureViolations.length} fixture violation(s):\n`);
+    for (const v of fixtureViolations) {
+      console.error(`  fixtures/${v.fixture}  [${v.rule}] ${v.detail}`);
+    }
+  }
+
+  if (softFindings.length > 0) {
+    console.warn(
+      `\n[check-integration-isolation] ${softFindings.length} soft finding(s) (remaining framework bleed-through — migrate in follow-up PRs; run with MIGRATION_STRICT=1 to fail on these):\n`,
+    );
+    for (const f of softFindings) {
+      console.warn(`  ${f.file}:${f.line}  ${f.description}`);
+      console.warn(`    ${f.text}`);
+    }
+  }
+
+  process.exit(allViolations.length > 0 || fixtureViolations.length > 0 ? 1 : 0);
+}
+
+main();

package/scripts/check-new-file-tests.mjs

@@ -9,8 +9,8 @@
  *   --base: CI_MERGE_REQUEST_TARGET_BRANCH_NAME (MR) or origin/main (fallback)
  *
  * Exit codes:
- *   0 — all new files have tests (or no new files)
- *   1 — some new files are missing tests (warning)
+ *   0 — all new files have tests, no new files, or warning-mode findings
+ *   1 — strict mode only: some new files are missing tests
  */
 
 import { execSync } from "node:child_process";
@@ -51,6 +51,9 @@ const EXEMPT_PATH_PREFIXES = [
 /** Directories where backend tests live (searched for basename match). */
 const BACKEND_TEST_DIRS = ["tests/unit", "tests/integration"];
 
+/** Warning by default; set CHECK_NEW_FILE_TESTS_STRICT=1 to fail on findings. */
+const STRICT = process.env.CHECK_NEW_FILE_TESTS_STRICT === "1";
+
 // ── Helpers ────────────────────────────────────────────────────────────
 
 function git(cmd) {
@@ -188,4 +191,9 @@ console.log(
   "See docs/testing.md for testing conventions.\n",
 );
 
-process.exit(1);
+if (STRICT) {
+  process.exit(1);
+}
+
+console.log("Warning mode: findings reported but not blocking CI. Set CHECK_NEW_FILE_TESTS_STRICT=1 to fail.");
+process.exit(0);

package/scripts/check-open-core-boundaries.mjs

@@ -89,7 +89,11 @@ violations.push(
 
 violations.push(
   ...serviceFiles
-    .filter((file) => !adminFiles.includes(file) && !runtimeFiles.includes(file))
+    .filter((file) =>
+      !adminFiles.includes(file)
+      && !runtimeFiles.includes(file)
+      && !file.endsWith("/routes.ts"),
+    )
     .flatMap((file) =>
       lineViolations(file, [
         { pattern: /from\s+["'][^"']*routes\//, message: "service must not import routes" },
@@ -107,13 +111,24 @@ violations.push(
   ),
 );
 
+for (const file of llmProxyFiles) {
+  const path = rel(file);
+  const text = readFileSync(file, "utf8");
+  if (/panel\.json/.test(text)) {
+    violations.push(`${path} reads legacy panel.json; only legacy-migrator may import Panel provider settings`);
+  }
+  if (/raw\.providerId/.test(text)) {
+    violations.push(`${path} accepts legacy providerId as a canonical provider id; move that conversion into legacy-migrator`);
+  }
+}
+
 violations.push(
   ...runtimeFiles.flatMap((file) =>
     lineViolations(file, [
       { pattern: /from\s+["'][^"']*routes\//, message: "runtime service must not import routes" },
-      { pattern: /from\s+["'][^"']*openclaw-routes(\.js|\.ts)?["']/, message: "runtime service must not import route adapters" },
+      { pattern: /from\s+["'][^"']*(openclaw-routes|integrations\/openclaw\/routes)(\.js|\.ts)?["']/, message: "runtime service must not import integration route modules" },
       { pattern: /import\s*\(\s*["'][^"']*routes\//, message: "runtime service must not import routes" },
-      { pattern: /import\s*\(\s*["'][^"']*openclaw-routes(\.js|\.ts)?["']/, message: "runtime service must not import route adapters" },
+      { pattern: /import\s*\(\s*["'][^"']*(openclaw-routes|integrations\/openclaw\/routes)(\.js|\.ts)?["']/, message: "runtime service must not import integration route modules" },
     ]),
   ),
 );
@@ -171,14 +186,46 @@ if (rootPackage.name !== "jishushell") {
 if (rootPackage.bin?.jishushell !== "./dist/cli.js") {
   violations.push("package.json bin must expose the CLI command as jishushell -> ./dist/cli.js");
 }
-if (rootPackage.bin?.["jishushell-gui"]) {
-  violations.push("default package.json must not expose jishushell-gui; the GUI bin is added only by the Core+Panel pack script");
+const allowedRootExports = new Set(["./core", "./config", "./auth", "./types", "./constants"]);
+for (const exportKey of Object.keys(rootPackage.exports ?? {})) {
+  if (!allowedRootExports.has(exportKey)) {
+    violations.push(
+      `package.json exports ${exportKey}; package exports must stay at product-level entry points and keep services/utils internal`,
+    );
+  }
+  if (exportKey.startsWith("./services/") || exportKey.startsWith("./utils/")) {
+    violations.push(`package.json exports internal module ${exportKey}; use ./core or a public HTTP/CLI API instead`);
+  }
+}
+for (const exportKey of allowedRootExports) {
+  if (!rootPackage.exports?.[exportKey]) {
+    violations.push(`package.json exports must include product-level entry ${exportKey}`);
+  }
+}
+const rootPanelDep = rootPackage.dependencies?.["jishushell-panel"];
+const rootOptionalPanelDep = rootPackage.optionalDependencies?.["jishushell-panel"];
+const rootPanelBundled =
+  rootPackage.bundleDependencies?.includes("jishushell-panel")
+  || rootPackage.bundledDependencies?.includes("jishushell-panel");
+const rootGuiBin = rootPackage.bin?.["jishushell-gui"];
+
+if (rootGuiBin) {
+  violations.push("package.json must not expose jishushell-gui in the source manifest; scripts/pack-with-gui.mjs injects it only for GUI release tarballs");
+}
+if (rootPanelDep) {
+  violations.push("package.json must not depend on jishushell-panel in the source manifest; GUI releases consume a prebuilt dependencies/ tarball through scripts/pack-with-gui.mjs");
+}
+if (rootOptionalPanelDep) {
+  violations.push("package.json must not place jishushell-panel under optionalDependencies; the source manifest must stay Core/CLI-only");
 }
-if (rootPackage.dependencies?.["jishushell-panel"] || rootPackage.optionalDependencies?.["jishushell-panel"]) {
-  violations.push("default Core/CLI package.json must not depend on jishushell-panel; Panel is only bundled by the Core+Panel pack script");
+if (rootPanelBundled) {
+  violations.push("package.json must not bundle jishushell-panel in the source manifest; GUI release packaging owns that composition");
 }
-if (rootPackage.bundleDependencies?.includes("jishushell-panel") || rootPackage.bundledDependencies?.includes("jishushell-panel")) {
-  violations.push("default Core/CLI package.json must not bundle jishushell-panel; Panel is only bundled by the Core+Panel pack script");
+if (rootPackage.scripts?.["release:pack"] !== "npm run build:pack:gui") {
+  violations.push("package.json release:pack must build the final GUI release tarball via npm run build:pack:gui");
+}
+if (rootPackage.scripts?.["build:pack:gui"] !== "npm run build && node scripts/pack-with-gui.mjs") {
+  violations.push("package.json build:pack:gui must use scripts/pack-with-gui.mjs to inject the prebuilt Panel tarball");
 }
 if (panelPackage) {
   if (panelPackage.name !== "jishushell-panel") {
@@ -224,6 +271,9 @@ for (const fileEntry of rootPackage.files ?? []) {
   if (fileEntry === "vendor/" || fileEntry === "build/") {
     violations.push(`package.json files includes ${fileEntry}; Core package must not ship vendored Panel release state`);
   }
+  if (/^dependencies\/jishushell-panel(?:[-.].*)?\.tgz$/.test(fileEntry)) {
+    violations.push(`package.json files includes ${fileEntry}; scripts/pack-with-gui.mjs adds the selected Panel tarball only for GUI release packaging`);
+  }
 }
 for (const relativePath of [
   "scripts/build-local-panel-bundle.mjs",
@@ -264,7 +314,7 @@ for (const file of srcFiles) {
 
 for (const file of [...cliFiles, ...serviceFiles]) {
   const path = rel(file);
-  if (path === "src/services/suggestions.ts") continue;
+  if (path === "src/services/connections/suggestions.ts") continue;
   const text = readFileSync(file, "utf8");
   const hits = hasImportLikeReference(text, [
     /["'][^"']*services\/suggestions(?:\.js|\.ts)?["']/,