@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

package/src/runtime/companion-guidance.ts

@@ -0,0 +1,222 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "./framework";
+import { GUIDANCE_FILE_VERSION, type MateGuidanceFile } from "./guidance";
+
+/**
+ * The guidance builders, on the session-runtime side of core.
+ *
+ * They live here rather than under `playbooks/` because a hook shim and the
+ * OpenCode plugin both have to build guidance without a launch, and both may
+ * only reach `runtime/` — the import-isolation tests enforce that. What kept
+ * them out was a single resolved default, `getWrapperBinPath()`; taking the
+ * path as data instead makes the whole set pure. `playbooks/companion-guidance`
+ * still supplies that default for the framework-side callers.
+ */
+
+/**
+ * What guidance actually reads off a launch context. Structurally satisfied by
+ * `AdapterContext`, so a launch passes its own context unchanged, and equally
+ * by a value composed from the projection.
+ */
+export interface GuidanceCapability {
+  name: string;
+}
+
+export interface GuidanceContext {
+  companionPath: string;
+  repository: { id: string; path: string };
+  capabilities?: GuidanceCapability[];
+}
+
+export function hasGraphifyCapability(capabilities: GuidanceCapability[] = []): boolean {
+  return capabilities.some((capability) => capability.name === "graphify");
+}
+
+export function hasOpenspecCapability(capabilities: GuidanceCapability[] = []): boolean {
+  return capabilities.some((capability) => capability.name === "openspec");
+}
+
+export function hasTokensaveCapability(capabilities: GuidanceCapability[] = []): boolean {
+  return capabilities.some((capability) => capability.name === "tokensave");
+}
+
+export const GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT =
+  "$MATE_ARTIFACT_PATH/.graphify/$MATE_REPO_ID/graphify-out/";
+
+export function buildCodebaseExplorationGuidanceSection(
+  options: {
+    useGraphify?: boolean;
+    useTokensave?: boolean;
+  } = {},
+): string {
+  const { useGraphify = false, useTokensave = false } = options;
+
+  if (!useGraphify && !useTokensave) {
+    return "";
+  }
+
+  if (useGraphify && useTokensave) {
+    return `<codebase-exploration-rules priority="mandatory">
+<path role="graphify-out">${GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT}</path>
+<trigger>Codebase-understanding: architecture, tracing, integrations, impact, "how does X work?"</trigger>
+<order>tokensave -> graphify -> grep/glob/read. MUST NOT skip steps.
+1. tokensave_context first.
+2. If tokensave is empty/file-only/irrelevant, run graphify query "<question>"; use graphify path/explain to deepen.
+3. Use grep/glob/read only after tokensave and graphify were tried.</order>
+<notes>Dirty graph files are expected. Use wiki/index.md for broad navigation; GRAPH_REPORT.md only if query/path/explain fall short.</notes>
+<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index.</post-edit>
+</codebase-exploration-rules>`;
+  }
+
+  if (useGraphify) {
+    return `<codebase-exploration-rules priority="mandatory">
+<path role="graphify-out">${GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT}</path>
+<trigger>Codebase-understanding: architecture, tracing, integrations, impact, "how does X work?"</trigger>
+<order>graphify -> grep/glob/read. MUST try graphify before raw source.
+1. graphify query "<question>" first.
+2. Use graphify path "<A>" "<B>" or graphify explain "<concept>" to deepen.
+3. Use grep/glob/read only after graphify was tried.</order>
+<notes>Dirty graph files are expected. Use wiki/index.md for broad navigation; GRAPH_REPORT.md only if query/path/explain fall short.</notes>
+<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index --graphify.</post-edit>
+</codebase-exploration-rules>`;
+  }
+
+  return `<codebase-exploration-rules priority="mandatory">
+<trigger>Codebase-understanding: architecture, tracing, integrations, impact, "how does X work?"</trigger>
+<order>tokensave -> grep/glob/read. MUST try tokensave before raw source.
+1. tokensave_context first.
+2. Use grep/glob/read only after tokensave is empty or irrelevant.</order>
+<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index --tokensave.</post-edit>
+</codebase-exploration-rules>`;
+}
+
+/**
+ * Build just the `<companion-policy>` XML block: paths, CLI tools, and
+ * mandatory rules (including the capability-gated `openspec-publish` rule).
+ * Does not include codebase-exploration guidance — see
+ * `buildCompanionGuidance` for the merged single-string form, or call
+ * `buildCodebaseExplorationGuidanceSection` directly when that guidance is
+ * delivered through its own channel (as OpenCode's guidance contract does).
+ */
+export function buildCompanionPolicyXml(
+  context: GuidanceContext,
+  options: { wrapperBinPath: string },
+): string {
+  const { wrapperBinPath } = options;
+  const lines = [
+    "## MANDATORY RULES - NON-NEGOTIABLE",
+    "",
+    `<companion-policy framework="${FRAMEWORK_NAME}" priority="mandatory">`,
+    `  <overview>You are operating inside the ${FRAMEWORK_NAME} companion repository.</overview>`,
+    "  <context>",
+    "    <paths>",
+    `      <path role="working-repository" env="MATE_REPO_PATH">${context.repository.path}</path>`,
+    `      <path role="companion-repository" env="MATE_ARTIFACT_PATH">${context.companionPath}</path>`,
+    `      <path role="package-wrapper-bin" env="MATE_WRAPPER_BIN_PATH">${wrapperBinPath}</path>`,
+    "    </paths>",
+    "    <cli-tools>",
+    `      <cli name="openspec" type="wrapper" invokeAs="${path.join(wrapperBinPath, "openspec")}" />`,
+    `      <cli name="graphify" type="wrapper" invokeAs="${path.join(wrapperBinPath, "graphify")}" />`,
+    `      <cli name="${FRAMEWORK_NAME}" type="global" invokeAs="${FRAMEWORK_NAME}" />`,
+    "    </cli-tools>",
+    `    <linked-repository id="${context.repository.id}" />`,
+    "  </context>",
+    "  <mandatory-rules>",
+    `    <rule id="artifact-location" severity="critical">Agent artifacts MUST go to ${context.companionPath}, NEVER ${context.repository.path}. Artifacts include plans, specs, ADRs, todos, notes, handoffs, reasoning docs, and scratch files.</rule>`,
+    `    <rule id="pre-write-classification" severity="critical">Before ANY write, classify the target as product-code or agent-artifact. If unsure, treat it as agent-artifact.</rule>`,
+    `    <rule id="product-code-location" severity="critical">Product code (README, docs, source, tests) belongs in ${context.repository.path}. Agent-artifacts belong in ${context.companionPath}.</rule>`,
+    `    <rule id="local-artifact-exception" severity="critical">Only write artifacts in ${context.repository.path} when the exact path is gitignored AND intentionally local-only; otherwise use ${context.companionPath}.</rule>`,
+    `    <rule id="guardrail" severity="critical">Bad artifact writes to ${context.repository.path} are rejected. Classify correctly first.</rule>`,
+    `    <rule id="companion-multi-repository" severity="critical">This Companion Repository may serve multiple Working Repositories. The working-repository path above identifies this session's single primary Working Repository, not the companion's full repository set. The Companion Repository is the shared artifact and context plane; the primary Working Repository is the product-code plane.</rule>`,
+    `    <rule id="repository-area-scope" severity="critical">For domain modeling, identify the canonical Working Repository and its repository-relative Area first. A checkout basename or Area alone is not a repository identity. Shared context applies only when the Companion Repository's CONTEXT-MAP explicitly maps it to the current repository and Area.</rule>`,
+    `    <rule id="wrapper-only-cli-execution" severity="critical">For every CLI declared in cli-tools, invoke the exact path in its invokeAs attribute. Correct: ${path.join(wrapperBinPath, "openspec")} status ... . Incorrect: openspec status ... . Do not run bare openspec or graphify commands and do not rely on PATH, aliases, or shell functions. If the exact wrapper path is unavailable, stop and report it.</rule>`,
+  ];
+
+  if (hasOpenspecCapability(context.capabilities)) {
+    lines.push(
+      `    <rule id="openspec-scope" severity="critical">In OpenSpec, the frontmatter repository identifies the Working Repository. areas are repository-relative paths within that repository. Canonical specs use repository plus flat areas; change artifacts use paired scopes entries. In a monorepo, an Area normally stops at the package root. A cross-repository change may declare multiple scopes, but each resulting spec remains owned by one repository, and each requirement must bind its Area explicitly.</rule>`,
+      `    <rule id="openspec-publish" severity="critical">Archiving an OpenSpec change is a local operation and publishes nothing. Publish through the mate-artifact-publish skill: it lists candidates with ${FRAMEWORK_NAME} artifact pending --json, takes an explicit user selection, confirms the commit, tag, and push, then runs ${FRAMEWORK_NAME} artifact publish "<name>" --json per selected change. That command is the only sanctioned publication; never hand-commit or hand-tag one. Publishing only publishes an already-archived change: archiving is a precondition, and running publish on a still-active change is an error that names openspec archive as the missing step. Publish never archives and never applies delta specs itself, so archive first — by the archive workflow or an already-synced flow such as openspec-sync-specs — and then publish. Publish also refuses to run anywhere but the companion's default branch.</rule>`,
+    );
+  }
+
+  lines.push("  </mandatory-rules>");
+
+  lines.push("</companion-policy>");
+
+  return lines.join("\n");
+}
+
+/**
+ * Build the merged single-string guidance: the companion-policy XML plus
+ * codebase-exploration guidance appended when graphify or tokensave is
+ * enabled. Used by providers (e.g. Claude) that inject one combined prompt
+ * fragment rather than delivering exploration guidance separately.
+ */
+export function buildCompanionGuidance(
+  context: GuidanceContext,
+  options: { wrapperBinPath: string },
+): string {
+  const lines = [buildCompanionPolicyXml(context, options)];
+
+  const graphifyEnabled = hasGraphifyCapability(context.capabilities);
+  const tokensaveEnabled = hasTokensaveCapability(context.capabilities);
+
+  if (graphifyEnabled || tokensaveEnabled) {
+    lines.push(
+      "",
+      buildCodebaseExplorationGuidanceSection({
+        useGraphify: graphifyEnabled,
+        useTokensave: tokensaveEnabled,
+      }),
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build the companion guidance payload the OpenCode plugin consumes, whether
+ * delivered through `MATE_GUIDANCE_JSON` by a launch or built from the
+ * Projection Root by the plugin itself. The text carries `$MATE_*`
+ * placeholders the plugin materializes from its own resolved context, so the
+ * same payload shape serves every companion and no path is resolved here.
+ *
+ * Real capabilities are passed through (not just the graphify/tokensave flags)
+ * so capability-gated companion-policy rules — e.g. openspec-publish — render
+ * exactly as they do for the Claude provider.
+ */
+export function buildOpenCodeGuidance(capabilities: GuidanceCapability[]): MateGuidanceFile {
+  const companionGuidance = buildCompanionPolicyXml(
+    {
+      companionPath: "$MATE_ARTIFACT_PATH",
+      repository: { id: "$MATE_REPO_ID", path: "$MATE_REPO_PATH" },
+      capabilities,
+    },
+    { wrapperBinPath: "$MATE_WRAPPER_BIN_PATH" },
+  );
+  const graphifyEnabled = hasGraphifyCapability(capabilities);
+  const tokensaveEnabled = hasTokensaveCapability(capabilities);
+  const codebaseExplorationGuidance = buildCodebaseExplorationGuidanceSection({
+    useGraphify: graphifyEnabled,
+    useTokensave: tokensaveEnabled,
+  });
+  const errors: string[] = [];
+
+  if (!companionGuidance.includes("<companion-policy ")) {
+    errors.push("companion guidance was not injected");
+  }
+  if (
+    (graphifyEnabled || tokensaveEnabled) &&
+    !codebaseExplorationGuidance.includes("<codebase-exploration-rules ")
+  ) {
+    errors.push("codebase exploration guidance was not injected");
+  }
+
+  return {
+    version: GUIDANCE_FILE_VERSION,
+    companionGuidance,
+    codebaseExplorationGuidance,
+    errors,
+  };
+}

package/src/runtime/companion-sync.ts

@@ -0,0 +1,298 @@
+/**
+ * The unattended half of companion Git synchronization: fetch, then
+ * fast-forward when the companion is strictly behind. Everything a human must
+ * answer — divergence, a dirty tree, credentials, an in-progress merge — is
+ * reported rather than attempted.
+ *
+ * Lives under `runtime/` because the session-start hooks need it and may not
+ * import `lib/orchestrator`. Synchronous for the same reason: the Claude hook
+ * that calls it is synchronous.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  companionGitStatePath,
+  COMPANION_SYNC_TTL_MS,
+  FORK_VERDICT_TTL_MS,
+  isCompanionSyncDue,
+  readCachedForkRecord,
+  readCompanionGitRecord,
+  recordCompanionSync,
+  recordCompanionSyncUnfinished,
+  recordForkVerdict,
+} from "./companion-git-state";
+import {
+  companionForkState,
+  describeGitFailure,
+  forkStateAgainst,
+  GIT_QUERY_TIMEOUT_MS,
+  isAuthenticationFailure,
+  outputLines,
+  resolveUpstreamTargetSync,
+  runGitSync,
+  type CompanionForkState,
+} from "./companion-git";
+import { hasLaunchEnvironment } from "./env";
+import { FRAMEWORK_NAME } from "./framework";
+import { readCompanionPolicy } from "./policy";
+
+/** The one command that finishes what the unattended half declines to do. */
+export const COMPANION_SYNC_COMMAND = `${FRAMEWORK_NAME} companion sync`;
+
+/** A cold link costs this once; the recorded completion then suppresses retries. */
+export const COMPANION_SYNC_TIMEOUT_MS = 20_000;
+
+export type UnattendedSyncStatus = "not-applicable" | "fresh" | "complete" | "unfinished";
+
+export interface UnattendedSyncOutcome {
+  status: UnattendedSyncStatus;
+  changed: boolean;
+  companionPath: string;
+  /** Set for `unfinished`: what a human must resolve. */
+  reason?: string;
+}
+
+export interface UnattendedSyncOptions {
+  ttlMs?: number;
+  timeoutMs?: number;
+  now?: Date;
+  homeDir?: string;
+  env?: Record<string, string | undefined>;
+}
+
+const UNFINISHED_GIT_PATHS = [
+  "MERGE_HEAD",
+  "CHERRY_PICK_HEAD",
+  "REVERT_HEAD",
+  "rebase-merge",
+  "rebase-apply",
+];
+
+function hasGitPath(companionPath: string, name: string, timeoutMs: number): boolean {
+  const gitPath = runGitSync(companionPath, ["rev-parse", "--git-path", name], timeoutMs);
+  if (gitPath.status !== 0) return false;
+  return fs.existsSync(path.resolve(companionPath, gitPath.stdout.trim()));
+}
+
+function notApplicable(companionPath: string): UnattendedSyncOutcome {
+  return { status: "not-applicable", changed: false, companionPath };
+}
+
+function unfinished(
+  companionPath: string,
+  reason: string,
+  homeDir: string | undefined,
+): UnattendedSyncOutcome {
+  /** Persisted so a reader that renders session state can surface it without re-running Git. */
+  recordCompanionSyncUnfinished(companionPath, reason, homeDir);
+  return { status: "unfinished", changed: false, companionPath, reason };
+}
+
+/**
+ * The consent gate is held here, before any process is spawned, so that
+ * reaching this function at all is enough to be safe — no caller can widen the
+ * operator's standing answer to "may Mate touch my Git".
+ */
+export function syncCompanionUnattended(
+  companionPath: string,
+  options: UnattendedSyncOptions = {},
+): UnattendedSyncOutcome {
+  const {
+    ttlMs = COMPANION_SYNC_TTL_MS,
+    timeoutMs = COMPANION_SYNC_TIMEOUT_MS,
+    now = new Date(),
+    homeDir,
+  } = options;
+
+  if (!companionPath) return notApplicable(companionPath);
+  if (!readCompanionPolicy(companionPath).gitAutoMode) return notApplicable(companionPath);
+  if (!isCompanionSyncDue(companionPath, ttlMs, now, homeDir)) {
+    return { status: "fresh", changed: false, companionPath };
+  }
+
+  const deadline = now.getTime() + timeoutMs;
+  const remaining = () => Math.max(1, deadline - Date.now());
+
+  const target = resolveUpstreamTargetSync(
+    companionPath,
+    Math.min(GIT_QUERY_TIMEOUT_MS, remaining()),
+  );
+  if (!target) return notApplicable(companionPath);
+
+  const inProgress = UNFINISHED_GIT_PATHS.filter((name) =>
+    hasGitPath(companionPath, name, Math.min(GIT_QUERY_TIMEOUT_MS, remaining())),
+  );
+  if (inProgress.length > 0) {
+    return unfinished(
+      companionPath,
+      `an unfinished Git operation is in progress (${inProgress.join(", ")})`,
+      homeDir,
+    );
+  }
+
+  const fetch = runGitSync(
+    companionPath,
+    ["fetch", "--no-progress", target.remote, target.branch],
+    remaining(),
+  );
+  if (fetch.status !== 0) {
+    if (isAuthenticationFailure(fetch)) {
+      return unfinished(companionPath, `fetching ${target.ref} needs Git authentication`, homeDir);
+    }
+    return unfinished(
+      companionPath,
+      `unable to fetch ${target.ref}: ${describeGitFailure(fetch)}`,
+      homeDir,
+    );
+  }
+
+  const fork = forkStateAgainst(
+    companionPath,
+    target.ref,
+    Math.min(GIT_QUERY_TIMEOUT_MS, remaining()),
+  );
+  if (!fork) return notApplicable(companionPath);
+
+  if (fork.behind === 0) {
+    recordCompanionSync(companionPath, now, homeDir);
+    return { status: "complete", changed: false, companionPath };
+  }
+  if (fork.ahead > 0) {
+    return unfinished(
+      companionPath,
+      `history has diverged from ${target.ref} (${fork.ahead} ahead, ${fork.behind} behind)`,
+      homeDir,
+    );
+  }
+
+  const merge = runGitSync(
+    companionPath,
+    ["merge", "--ff-only", "--no-stat", "--no-progress", target.ref],
+    Math.min(GIT_QUERY_TIMEOUT_MS, remaining()),
+  );
+  if (merge.status !== 0) {
+    const dirty = runGitSync(
+      companionPath,
+      ["status", "--porcelain=v1", "--untracked-files=all"],
+      Math.min(GIT_QUERY_TIMEOUT_MS, remaining()),
+    );
+    if (dirty.status === 0 && outputLines(dirty.stdout).length > 0) {
+      return unfinished(
+        companionPath,
+        `local changes block the fast-forward to ${target.ref}`,
+        homeDir,
+      );
+    }
+    return unfinished(
+      companionPath,
+      `unable to fast-forward to ${target.ref}: ${describeGitFailure(merge)}`,
+      homeDir,
+    );
+  }
+
+  recordCompanionSync(companionPath, now, homeDir);
+  return { status: "complete", changed: true, companionPath };
+}
+
+/**
+ * Operator-facing only. This text must never reach a model-visible channel: a
+ * model told to run the command will run it unattended, with no terminal to
+ * answer a credential prompt and no way to tell a fast-forward from a
+ * conflicted rebase.
+ */
+export function unattendedSyncStalenessLines(outcome: UnattendedSyncOutcome): string[] {
+  if (outcome.status !== "unfinished") return [];
+  return [
+    `companion Git synchronization unfinished: ${outcome.reason ?? "unknown reason"} — run \`${COMPANION_SYNC_COMMAND}\``,
+  ];
+}
+
+/**
+ * The note a session-state reader surfaces, taken from the persisted record so
+ * a render costs no Git. Operator-facing only, exactly as the live note is.
+ */
+export function persistedCompanionGitStalenessLines(
+  companionPath: string,
+  homeDir?: string,
+): string[] {
+  if (!companionPath) return [];
+  const reason = readCompanionGitRecord(companionPath, homeDir).unfinishedReason;
+  if (!reason) return [];
+  return unattendedSyncStalenessLines({
+    status: "unfinished",
+    changed: false,
+    companionPath,
+    reason,
+  });
+}
+
+export interface ForkGuardOptions {
+  ttlMs?: number;
+  timeoutMs?: number;
+  now?: Date;
+  homeDir?: string;
+}
+
+/**
+ * The verdict both runtimes' artifact guards share, cached per interval so a
+ * retry loop cannot spawn Git per write. `null` means "no refusal" — including
+ * every case in which the check could not be completed, because the guard must
+ * never fail closed.
+ */
+export function companionForkRefusal(
+  env: Record<string, string | undefined>,
+  companionPath: string,
+  options: ForkGuardOptions = {},
+): string | null {
+  if (!companionPath) return null;
+  /**
+   * A Managed Launch has already settled this session's Git question — by its
+   * preflight, by `--no-git`, or by a companion whose Git handling is not
+   * automatic. Refusing afterwards would revoke a documented bypass mid-session.
+   */
+  if (hasLaunchEnvironment(env)) return null;
+  /** The same consent gate the repair holds: Git handling off makes this inert. */
+  if (!readCompanionPolicy(companionPath).gitAutoMode) return null;
+
+  const fork = cachedCompanionForkState(companionPath, options);
+  if (!fork?.forked) return null;
+  return forkRefusalMessage(companionPath, fork);
+}
+
+export function cachedCompanionForkState(
+  companionPath: string,
+  options: ForkGuardOptions = {},
+): CompanionForkState | null {
+  const {
+    ttlMs = FORK_VERDICT_TTL_MS,
+    timeoutMs = GIT_QUERY_TIMEOUT_MS,
+    now = new Date(),
+    homeDir,
+  } = options;
+
+  const cached = readCachedForkRecord(companionPath, ttlMs, now, homeDir);
+  if (cached) {
+    return {
+      ahead: cached.ahead,
+      behind: cached.behind,
+      forked: cached.ahead > 0 && cached.behind > 0,
+    };
+  }
+
+  const fork = companionForkState(companionPath, timeoutMs);
+  if (!fork) return null;
+  recordForkVerdict(companionPath, { ahead: fork.ahead, behind: fork.behind }, now, homeDir);
+  return fork;
+}
+
+export function forkRefusalMessage(companionPath: string, fork: CompanionForkState): string {
+  return [
+    `${FRAMEWORK_NAME} guardrail: the companion's history has forked from its upstream.`,
+    ` companion: ${companionPath}`,
+    ` ${fork.ahead} local commit(s) ahead, ${fork.behind} upstream commit(s) behind`,
+    `Writing artifacts now risks losing work in the reconciliation. Run \`${COMPANION_SYNC_COMMAND}\` first.`,
+  ].join("\n");
+}
+
+export { companionGitStatePath };

package/src/runtime/env-names.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ *
+ * Every name is `MATE_`-prefixed, which is what lets a reader treat "any of
+ * these present" as "a Mate launch configured this process".
+ */
+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",
+  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];

package/src/runtime/env.ts

@@ -1,35 +1,14 @@
-/**
- * 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",
-  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;
+import { MATE_ENV } from "./env-names";
+import { FRAMEWORK_NAME } from "./framework";
+import { isCapabilityEnabled, readCompanionPolicy } from "./policy";
+import { resolveProjection, type ResolvedProjection } from "./projection";
 
-export type MateEnvVariable = (typeof MATE_ENV)[keyof typeof MATE_ENV];
+export { MATE_ENV, type MateEnvVariable } from "./env-names";
 
 /**
- * Normalized companion runtime context derived from the Mate launch
- * environment. Contains no repository-specific defaults; every value comes
- * from the active session environment.
+ * Normalized companion runtime context. Values come from the Mate launch
+ * environment when it is present, and from the durable projection at the
+ * Projection Root otherwise.
  */
 export type CompanionRuntimeContext = {
   frameworkName: string;
@@ -42,11 +21,17 @@ export type CompanionRuntimeContext = {
   reactDoctorEnabled: boolean;
 };
 
-export function readCompanionRuntimeContext(
-  env: Record<string, string | undefined> = process.env,
-): CompanionRuntimeContext {
+/**
+ * Any `MATE_*` variable present means a Mate launch configured this process,
+ * so the environment is authoritative and the projection is not read.
+ */
+export function hasLaunchEnvironment(env: Record<string, string | undefined>): boolean {
+  return Object.values(MATE_ENV).some((name) => env[name] !== undefined);
+}
+
+function fromEnvironment(env: Record<string, string | undefined>): CompanionRuntimeContext {
   return {
-    frameworkName: env[MATE_ENV.frameworkName] ?? "mate",
+    frameworkName: env[MATE_ENV.frameworkName] ?? FRAMEWORK_NAME,
     companionPath: env[MATE_ENV.companionPath] ?? "",
     repositoryPath: env[MATE_ENV.repositoryPath] ?? "",
     repositoryId: env[MATE_ENV.repositoryId] ?? "",
@@ -58,8 +43,55 @@ export function readCompanionRuntimeContext(
 }
 
 /**
- * A session is Mate-managed only when the CLI exported both the companion
- * path and the working repository path. Plugins must stay inert otherwise.
+ * The resolved context together with the projection it came from, so a reader
+ * that surfaces session state can judge that projection's freshness without a
+ * second upward walk. `projection` is null for a managed session.
+ */
+export interface CompanionRuntimeResolution {
+  context: CompanionRuntimeContext;
+  projection: ResolvedProjection | null;
+}
+
+/**
+ * The environment always wins: the projection is consulted only when no
+ * `MATE_*` variable is set, so a managed session never reads it and no stale
+ * or malformed projection can degrade a session a Mate launch configured.
+ */
+export function resolveCompanionRuntime(
+  env: Record<string, string | undefined> = process.env,
+  cwd: string = process.cwd(),
+): CompanionRuntimeResolution {
+  if (hasLaunchEnvironment(env)) return { context: fromEnvironment(env), projection: null };
+
+  const projection = resolveProjection(cwd);
+  if (!projection) return { context: fromEnvironment(env), projection: null };
+
+  const policy = readCompanionPolicy(projection.companionPath);
+  return {
+    projection,
+    context: {
+      frameworkName: FRAMEWORK_NAME,
+      companionPath: projection.companionPath,
+      repositoryPath: projection.repositoryPath,
+      repositoryId: projection.repositoryId,
+      policyJson: JSON.stringify({ allowedAgents: policy.allowedAgents }),
+      graphifyEnabled: isCapabilityEnabled(policy, "graphify"),
+      gitAutoModeEnabled: policy.gitAutoMode,
+      reactDoctorEnabled: isCapabilityEnabled(policy, "react-doctor"),
+    },
+  };
+}
+
+export function readCompanionRuntimeContext(
+  env: Record<string, string | undefined> = process.env,
+  cwd: string = process.cwd(),
+): CompanionRuntimeContext {
+  return resolveCompanionRuntime(env, cwd).context;
+}
+
+/**
+ * A session is Mate-managed only when both the companion path and the working
+ * repository path resolved. Plugins must stay inert otherwise.
  */
 export function isManagedCompanionContext(context: CompanionRuntimeContext): boolean {
   return Boolean(context.companionPath && context.repositoryPath);