@uniqbit/mate-core 0.15.0-canary.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@uniqbit/mate-core",
+  "version": "0.15.0-canary.0",
+  "description": "Shared Mate companion runtime protocol: launch environment and guidance-file contract.",
+  "license": "MIT",
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "CI=1 bun test",
+    "lint": "oxlint src/",
+    "lint:fix": "oxlint src/ --fix",
+    "format": "oxfmt src/",
+    "format:check": "oxfmt src/ --check"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "packageManager": "bun@1.3.14"
+}

package/src/env.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+
+import { MATE_ENV, isManagedCompanionContext, readCompanionRuntimeContext } from "./env";
+
+describe("MATE_ENV", () => {
+  test("exposes the stable launch environment variable names", () => {
+    expect(MATE_ENV.frameworkName).toBe("MATE_NAME");
+    expect(MATE_ENV.version).toBe("MATE_VERSION");
+    expect(MATE_ENV.companionPath).toBe("MATE_ARTIFACT_PATH");
+    expect(MATE_ENV.wrapperBinPath).toBe("MATE_WRAPPER_BIN_PATH");
+    expect(MATE_ENV.repositoryPath).toBe("MATE_REPO_PATH");
+    expect(MATE_ENV.repositoryId).toBe("MATE_REPO_ID");
+    expect(MATE_ENV.repositoryProfile).toBe("MATE_REPO_PROFILE");
+    expect(MATE_ENV.policyJson).toBe("MATE_POLICY_JSON");
+    expect(MATE_ENV.graphifyEnabled).toBe("MATE_GRAPHIFY_ENABLED");
+    expect(MATE_ENV.gitAutoMode).toBe("MATE_GIT_AUTO_MODE");
+    expect(MATE_ENV.reactDoctorEnabled).toBe("MATE_REACT_DOCTOR_ENABLED");
+    expect(MATE_ENV.reactDoctorBinPath).toBe("MATE_REACT_DOCTOR_BIN_PATH");
+    expect(MATE_ENV.guidanceJson).toBe("MATE_GUIDANCE_JSON");
+  });
+});
+
+describe("readCompanionRuntimeContext", () => {
+  test("normalizes a fully managed environment", () => {
+    const context = readCompanionRuntimeContext({
+      MATE_NAME: "acme-mate",
+      MATE_ARTIFACT_PATH: "/companions/acme",
+      MATE_REPO_PATH: "/repos/acme",
+      MATE_REPO_ID: "acme",
+      MATE_REPO_PROFILE: "default",
+      MATE_POLICY_JSON: '{"allowedAgents":["opencode"]}',
+      MATE_GRAPHIFY_ENABLED: "1",
+      MATE_GIT_AUTO_MODE: "0",
+      MATE_REACT_DOCTOR_ENABLED: "1",
+    });
+
+    expect(context).toEqual({
+      frameworkName: "acme-mate",
+      companionPath: "/companions/acme",
+      repositoryPath: "/repos/acme",
+      repositoryId: "acme",
+      repositoryProfile: "default",
+      policyJson: '{"allowedAgents":["opencode"]}',
+      graphifyEnabled: true,
+      gitAutoModeEnabled: false,
+      reactDoctorEnabled: true,
+    });
+  });
+
+  test("falls back to inert defaults when the environment is unmanaged", () => {
+    const context = readCompanionRuntimeContext({});
+
+    expect(context.frameworkName).toBe("mate");
+    expect(context.companionPath).toBe("");
+    expect(context.repositoryPath).toBe("");
+    expect(context.policyJson).toBe("{}");
+    expect(context.graphifyEnabled).toBe(false);
+    expect(context.gitAutoModeEnabled).toBe(false);
+    expect(context.reactDoctorEnabled).toBe(false);
+  });
+
+  test("treats non-'1' flag values as disabled", () => {
+    const context = readCompanionRuntimeContext({
+      MATE_GRAPHIFY_ENABLED: "true",
+      MATE_GIT_AUTO_MODE: "yes",
+      MATE_REACT_DOCTOR_ENABLED: "0",
+    });
+
+    expect(context.graphifyEnabled).toBe(false);
+    expect(context.gitAutoModeEnabled).toBe(false);
+    expect(context.reactDoctorEnabled).toBe(false);
+  });
+});
+
+describe("isManagedCompanionContext", () => {
+  test("requires both companion and repository paths", () => {
+    const managed = readCompanionRuntimeContext({
+      MATE_ARTIFACT_PATH: "/companions/acme",
+      MATE_REPO_PATH: "/repos/acme",
+    });
+    const missingRepo = readCompanionRuntimeContext({
+      MATE_ARTIFACT_PATH: "/companions/acme",
+    });
+    const missingCompanion = readCompanionRuntimeContext({
+      MATE_REPO_PATH: "/repos/acme",
+    });
+
+    expect(isManagedCompanionContext(managed)).toBe(true);
+    expect(isManagedCompanionContext(missingRepo)).toBe(false);
+    expect(isManagedCompanionContext(missingCompanion)).toBe(false);
+  });
+});

package/src/env.ts

@@ -0,0 +1,69 @@
+/**
+ * Stable Mate launch environment contract shared by the CLI (writer) and the
+ * OpenCode runtime plugins (readers). The CLI materializes these variables for
+ * every managed session; plugins must consume them through this module instead
+ * of hard-coding variable names.
+ */
+export const MATE_ENV = {
+  frameworkName: "MATE_NAME",
+  version: "MATE_VERSION",
+  companionPath: "MATE_ARTIFACT_PATH",
+  wrapperBinPath: "MATE_WRAPPER_BIN_PATH",
+  repositoryPath: "MATE_REPO_PATH",
+  repositoryId: "MATE_REPO_ID",
+  repositoryProfile: "MATE_REPO_PROFILE",
+  policyJson: "MATE_POLICY_JSON",
+  graphifyEnabled: "MATE_GRAPHIFY_ENABLED",
+  gitAutoMode: "MATE_GIT_AUTO_MODE",
+  reactDoctorEnabled: "MATE_REACT_DOCTOR_ENABLED",
+  reactDoctorBinPath: "MATE_REACT_DOCTOR_BIN_PATH",
+  /**
+   * Serialized `MateGuidanceFile` JSON built by the CLI per managed launch.
+   * Session-scoped: the plugin consumes it at startup and masks it from
+   * spawned shells so it never leaks into subprocess environments.
+   */
+  guidanceJson: "MATE_GUIDANCE_JSON",
+} as const;
+
+export type MateEnvVariable = (typeof MATE_ENV)[keyof typeof MATE_ENV];
+
+/**
+ * Normalized companion runtime context derived from the Mate launch
+ * environment. Contains no repository-specific defaults; every value comes
+ * from the active session environment.
+ */
+export type CompanionRuntimeContext = {
+  frameworkName: string;
+  companionPath: string;
+  repositoryPath: string;
+  repositoryId: string;
+  repositoryProfile: string;
+  policyJson: string;
+  graphifyEnabled: boolean;
+  gitAutoModeEnabled: boolean;
+  reactDoctorEnabled: boolean;
+};
+
+export function readCompanionRuntimeContext(
+  env: Record<string, string | undefined> = process.env,
+): CompanionRuntimeContext {
+  return {
+    frameworkName: env[MATE_ENV.frameworkName] ?? "mate",
+    companionPath: env[MATE_ENV.companionPath] ?? "",
+    repositoryPath: env[MATE_ENV.repositoryPath] ?? "",
+    repositoryId: env[MATE_ENV.repositoryId] ?? "",
+    repositoryProfile: env[MATE_ENV.repositoryProfile] ?? "",
+    policyJson: env[MATE_ENV.policyJson] ?? "{}",
+    graphifyEnabled: env[MATE_ENV.graphifyEnabled] === "1",
+    gitAutoModeEnabled: env[MATE_ENV.gitAutoMode] === "1",
+    reactDoctorEnabled: env[MATE_ENV.reactDoctorEnabled] === "1",
+  };
+}
+
+/**
+ * A session is Mate-managed only when the CLI exported both the companion
+ * path and the working repository path. Plugins must stay inert otherwise.
+ */
+export function isManagedCompanionContext(context: CompanionRuntimeContext): boolean {
+  return Boolean(context.companionPath && context.repositoryPath);
+}

package/src/guidance.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  CODEBASE_EXPLORATION_MARKER,
+  COMPANION_POLICY_MARKER,
+  GUIDANCE_FILE_VERSION,
+  parseGuidanceContent,
+  validateGuidanceData,
+} from "./guidance";
+import { MATE_ENV } from "./env";
+
+const validGuidance = {
+  version: 1,
+  companionGuidance: `${COMPANION_POLICY_MARKER}framework="mate">policy</companion-policy>`,
+  codebaseExplorationGuidance: `${CODEBASE_EXPLORATION_MARKER}priority="mandatory">rules</codebase-exploration-rules>`,
+  errors: [],
+};
+
+describe("guidance contract constants", () => {
+  test("delivery variable and version are stable", () => {
+    expect(MATE_ENV.guidanceJson).toBe("MATE_GUIDANCE_JSON");
+    expect(GUIDANCE_FILE_VERSION).toBe(1);
+  });
+});
+
+describe("validateGuidanceData", () => {
+  test("accepts a valid guidance payload", () => {
+    const result = validateGuidanceData(validGuidance);
+
+    expect(result.errors).toEqual([]);
+    expect(result.guidance.companionGuidance).toBe(validGuidance.companionGuidance);
+    expect(result.guidance.codebaseExplorationGuidance).toBe(
+      validGuidance.codebaseExplorationGuidance,
+    );
+  });
+
+  test("accepts empty codebase exploration guidance", () => {
+    const result = validateGuidanceData({
+      ...validGuidance,
+      codebaseExplorationGuidance: "",
+    });
+
+    expect(result.errors).toEqual([]);
+  });
+
+  test("rejects a non-object payload", () => {
+    expect(validateGuidanceData(null).errors).toEqual(["guidance data is not a JSON object"]);
+    expect(validateGuidanceData([]).errors).toEqual(["guidance data is not a JSON object"]);
+    expect(validateGuidanceData("guidance").errors).toEqual(["guidance data is not a JSON object"]);
+  });
+
+  test("rejects an unsupported version", () => {
+    const result = validateGuidanceData({ ...validGuidance, version: 2 });
+
+    expect(result.errors).toContain("unsupported guidance data version");
+  });
+
+  test("rejects missing companion guidance", () => {
+    const missing = validateGuidanceData({ ...validGuidance, companionGuidance: undefined });
+    const empty = validateGuidanceData({ ...validGuidance, companionGuidance: "   " });
+
+    expect(missing.errors).toContain("missing injected companion guidance");
+    expect(empty.errors).toContain("missing injected companion guidance");
+  });
+
+  test("rejects companion guidance without the policy marker", () => {
+    const result = validateGuidanceData({
+      ...validGuidance,
+      companionGuidance: "plain guidance without marker",
+    });
+
+    expect(result.errors).toContain("injected companion guidance is malformed");
+  });
+
+  test("rejects missing codebase exploration guidance field", () => {
+    const result = validateGuidanceData({
+      ...validGuidance,
+      codebaseExplorationGuidance: undefined,
+    });
+
+    expect(result.errors).toContain("missing injected codebase exploration guidance");
+  });
+
+  test("rejects non-empty codebase exploration guidance without its marker", () => {
+    const result = validateGuidanceData({
+      ...validGuidance,
+      codebaseExplorationGuidance: "rules without marker",
+    });
+
+    expect(result.errors).toContain("injected codebase exploration guidance is malformed");
+  });
+
+  test("carries embedded generation errors through", () => {
+    const result = validateGuidanceData({
+      ...validGuidance,
+      errors: ["companion guidance was not injected", "", 42],
+    });
+
+    expect(result.errors).toEqual(["companion guidance was not injected"]);
+  });
+});
+
+describe("parseGuidanceContent", () => {
+  test("parses and validates valid JSON content", () => {
+    const result = parseGuidanceContent(JSON.stringify(validGuidance));
+
+    expect(result.errors).toEqual([]);
+    expect(result.guidance.version).toBe(1);
+  });
+
+  test("reports invalid JSON without throwing", () => {
+    const result = parseGuidanceContent("{not json");
+
+    expect(result.errors).toEqual(["guidance data is not valid JSON"]);
+    expect(result.guidance.companionGuidance).toBe("");
+  });
+});

package/src/guidance.ts

@@ -0,0 +1,103 @@
+/**
+ * Versioned companion guidance contract. The CLI builds the guidance data
+ * from its playbooks at launch time and delivers it through the
+ * `MATE_GUIDANCE_JSON` launch environment variable (see `MATE_ENV`); the
+ * OpenCode plugin parses and validates it at session start.
+ */
+export const GUIDANCE_FILE_VERSION = 1;
+
+/** Marker every injected companion guidance block must contain. */
+export const COMPANION_POLICY_MARKER = "<companion-policy ";
+/** Marker every non-empty codebase exploration guidance block must contain. */
+export const CODEBASE_EXPLORATION_MARKER = "<codebase-exploration-rules ";
+
+export type MateGuidanceFile = {
+  version: number;
+  companionGuidance: string;
+  codebaseExplorationGuidance: string;
+  errors: string[];
+};
+
+export type GuidanceValidation = {
+  guidance: MateGuidanceFile;
+  errors: string[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function emptyGuidance(errors: string[]): GuidanceValidation {
+  return {
+    guidance: {
+      version: GUIDANCE_FILE_VERSION,
+      companionGuidance: "",
+      codebaseExplorationGuidance: "",
+      errors,
+    },
+    errors,
+  };
+}
+
+/**
+ * Validate an already-parsed guidance value against the versioned contract.
+ * Returns the normalized guidance data plus every contract violation found.
+ */
+export function validateGuidanceData(value: unknown): GuidanceValidation {
+  if (!isRecord(value)) {
+    return emptyGuidance(["guidance data is not a JSON object"]);
+  }
+
+  const errors = Array.isArray(value.errors)
+    ? value.errors.filter((entry): entry is string => typeof entry === "string" && Boolean(entry))
+    : [];
+
+  if (value.version !== GUIDANCE_FILE_VERSION) {
+    errors.push("unsupported guidance data version");
+  }
+
+  const companionGuidance =
+    typeof value.companionGuidance === "string" ? value.companionGuidance : "";
+  if (!companionGuidance.trim()) {
+    errors.push("missing injected companion guidance");
+  } else if (!companionGuidance.includes(COMPANION_POLICY_MARKER)) {
+    errors.push("injected companion guidance is malformed");
+  }
+
+  if (typeof value.codebaseExplorationGuidance !== "string") {
+    errors.push("missing injected codebase exploration guidance");
+  }
+  const codebaseExplorationGuidance =
+    typeof value.codebaseExplorationGuidance === "string" ? value.codebaseExplorationGuidance : "";
+  if (
+    codebaseExplorationGuidance.trim() &&
+    !codebaseExplorationGuidance.includes(CODEBASE_EXPLORATION_MARKER)
+  ) {
+    errors.push("injected codebase exploration guidance is malformed");
+  }
+
+  return {
+    guidance: {
+      version: GUIDANCE_FILE_VERSION,
+      companionGuidance,
+      codebaseExplorationGuidance,
+      errors,
+    },
+    errors,
+  };
+}
+
+/**
+ * Parse raw guidance JSON (the `MATE_GUIDANCE_JSON` value) and validate it
+ * against the contract.
+ */
+export function parseGuidanceContent(content: string): GuidanceValidation {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return emptyGuidance(["guidance data is not valid JSON"]);
+  }
+
+  return validateGuidanceData(parsed);
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  MATE_ENV,
+  isManagedCompanionContext,
+  readCompanionRuntimeContext,
+  type CompanionRuntimeContext,
+  type MateEnvVariable,
+} from "./env";
+export {
+  CODEBASE_EXPLORATION_MARKER,
+  COMPANION_POLICY_MARKER,
+  GUIDANCE_FILE_VERSION,
+  parseGuidanceContent,
+  validateGuidanceData,
+  type GuidanceValidation,
+  type MateGuidanceFile,
+} from "./guidance";