@uniqbit/mate-core 0.18.3 → 0.18.5

package/src/lib/orchestrator/openspec-store.ts

@@ -0,0 +1,202 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { parse as parseYaml } from "yaml";
+
+import { MATE_ENV } from "../../runtime/env-names";
+import { runtimeWrapperBinPath } from "../../runtime/runtime-directory";
+import { resolveCommandOnPath } from "../../tools/setup/utils";
+import { getWrapperBinPath } from "../package-paths";
+
+/**
+ * The Companion Repository as an OpenSpec store. OpenSpec reports the Working
+ * Repository as an edit root only when the CLI runs inside a project whose
+ * `openspec/config.yaml` declares a registered store, so the store has to be
+ * registered before any pointer may name it.
+ *
+ * Registration is checked by reading OpenSpec's registry file, never by
+ * spawning: the check runs on every session refresh. The CLI is spawned only to
+ * register, which OpenSpec answers authoritatively.
+ */
+
+const execFileAsync = promisify(execFile);
+
+/** OpenSpec's one id grammar, shared by store and change ids. */
+const KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+const STORE_METADATA_FILE = path.join(".openspec-store", "store.yaml");
+
+/** Injectable so the suite never touches the developer's registry or binary. */
+export const openSpecStoreDeps = {
+  env: (): NodeJS.ProcessEnv => process.env,
+  platform: (): NodeJS.Platform => process.platform,
+  homedir: (): string => os.homedir(),
+  /** Mate's own `openspec` wrappers, which must never answer a registration. */
+  wrapperBinDirs: (): string[] => {
+    const launched = openSpecStoreDeps.env()[MATE_ENV.wrapperBinPath];
+    return [getWrapperBinPath(), runtimeWrapperBinPath(), ...(launched ? [launched] : [])];
+  },
+  resolveBinary: (): string | undefined => {
+    const excluded = new Set(openSpecStoreDeps.wrapperBinDirs().map((dir) => path.resolve(dir)));
+    const searchPath = (openSpecStoreDeps.env().PATH ?? "")
+      .split(path.delimiter)
+      .filter((dir) => dir && !excluded.has(path.resolve(dir)))
+      .join(path.delimiter);
+    return resolveCommandOnPath("openspec", searchPath);
+  },
+};
+
+export type StoreRegistrationCheck =
+  | { state: "registered" }
+  | { state: "absent" }
+  | { state: "conflict"; path: string }
+  | { state: "unreadable" };
+
+export type StoreRegistration =
+  | { state: "written" | "current"; id: string }
+  | { state: "skipped"; reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function canonicalPath(candidate: string): Promise<string> {
+  return fs.realpath(candidate).catch(() => path.resolve(candidate));
+}
+
+async function isDirectory(candidate: string): Promise<boolean> {
+  return fs
+    .stat(candidate)
+    .then((stats) => stats.isDirectory())
+    .catch(() => false);
+}
+
+function sanitizeStoreId(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * The id a registration already recorded beside the companion, else the
+ * companion folder name made into a valid id. Machine-local on purpose: no
+ * artifact embeds it, and a committed one would collide across clones.
+ */
+export async function deriveStoreId(companionPath: string): Promise<string> {
+  const metadata = await fs
+    .readFile(path.join(companionPath, STORE_METADATA_FILE), "utf8")
+    .then((content) => parseYaml(content) as unknown)
+    .catch(() => null);
+  if (isRecord(metadata) && typeof metadata.id === "string" && KEBAB_ID.test(metadata.id)) {
+    return metadata.id;
+  }
+  const folder = path.basename(path.resolve(companionPath));
+  const id = sanitizeStoreId(folder);
+  if (!KEBAB_ID.test(id)) {
+    throw new Error(`cannot derive an OpenSpec store id from the companion folder "${folder}"`);
+  }
+  return id;
+}
+
+/** Mirrors OpenSpec's `getGlobalDataDir`, so Mate reads the registry OpenSpec writes. */
+export function openSpecDataDir(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+  homedir: string,
+): string {
+  if (env.XDG_DATA_HOME) return path.join(env.XDG_DATA_HOME, "openspec");
+  if (platform === "win32") {
+    return path.join(env.LOCALAPPDATA ?? path.join(homedir, "AppData", "Local"), "openspec");
+  }
+  return path.join(homedir, ".local", "share", "openspec");
+}
+
+function registryPath(): string {
+  return path.join(
+    openSpecDataDir(
+      openSpecStoreDeps.env(),
+      openSpecStoreDeps.platform(),
+      openSpecStoreDeps.homedir(),
+    ),
+    "stores",
+    "registry.yaml",
+  );
+}
+
+/** Read-only: what the registry says about `id`, compared by canonical path. */
+export async function checkStoreRegistration(
+  companionPath: string,
+  id: string,
+): Promise<StoreRegistrationCheck> {
+  let content: string;
+  try {
+    content = await fs.readFile(registryPath(), "utf8");
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT"
+      ? { state: "absent" }
+      : { state: "unreadable" };
+  }
+  let registry: unknown;
+  try {
+    registry = parseYaml(content);
+  } catch {
+    return { state: "unreadable" };
+  }
+  if (!isRecord(registry) || !isRecord(registry.stores)) return { state: "unreadable" };
+  const entry = registry.stores[id];
+  if (entry === undefined) return { state: "absent" };
+  const localPath =
+    isRecord(entry) && isRecord(entry.backend) ? entry.backend.local_path : undefined;
+  if (typeof localPath !== "string") return { state: "unreadable" };
+  return (await canonicalPath(localPath)) === (await canonicalPath(companionPath))
+    ? { state: "registered" }
+    : { state: "conflict", path: localPath };
+}
+
+function commandOutput(error: unknown): string {
+  const { stderr, stdout, message } = error as {
+    stderr?: string;
+    stdout?: string;
+    message: string;
+  };
+  return (stderr || stdout || message).trim();
+}
+
+/**
+ * Registers the companion when the registry lacks it. A conflicting id fails
+ * rather than silently picking another one; OpenSpec without stores, or a
+ * companion that is no OpenSpec root, is skipped.
+ */
+export async function ensureStoreRegistration(companionPath: string): Promise<StoreRegistration> {
+  const companion = await canonicalPath(companionPath);
+  if (!(await isDirectory(path.join(companion, "openspec")))) {
+    return { state: "skipped", reason: `${companion} is not an OpenSpec root` };
+  }
+  const id = await deriveStoreId(companion);
+  const check = await checkStoreRegistration(companion, id);
+  if (check.state === "registered") return { state: "current", id };
+  if (check.state === "conflict") {
+    throw new Error(`OpenSpec store id "${id}" is already registered at ${check.path}`);
+  }
+
+  const bin = openSpecStoreDeps.resolveBinary();
+  if (!bin) return { state: "skipped", reason: "the openspec CLI is not on PATH" };
+  try {
+    await execFileAsync(bin, ["store", "register", companion, "--id", id, "--yes"], {
+      cwd: companion,
+      env: openSpecStoreDeps.env(),
+      timeout: 30_000,
+    });
+  } catch (error) {
+    const output = commandOutput(error);
+    if (/unknown command/i.test(output)) {
+      return { state: "skipped", reason: "the openspec CLI does not support stores" };
+    }
+    throw new Error(`openspec store register failed: ${output}`, { cause: error });
+  }
+  return { state: "written", id };
+}

package/src/lib/orchestrator/projection-entries.ts

@@ -37,6 +37,15 @@ import {
   removeCompanionCopies,
   withdrawCompanionCopies,
 } from "./projection-opencode-copies";
+import {
+  OPENSPEC_POINTER_EXCLUDE,
+  OPENSPEC_POINTER_PATH,
+  projectStorePointer,
+  reconcileStorePointerExclude,
+  removeStorePointer,
+  removeStorePointerExclude,
+  storePointerPresent,
+} from "./projection-openspec-store";
 import { buildProjection } from "./projection-record";
 import {
   CLAUDE_WORKING_SETTINGS_PATH,
@@ -245,6 +254,42 @@ function buildEntries(): readonly ProjectionEntry[] {
         input.companionPath && input.repository ? writeProjectionPairEntry(input) : "skipped",
       removal: { by: "entry", entry: "projection-root" },
     },
+    /**
+     * The OpenSpec store pointer's exclusion, then the pointer: the line is on
+     * disk before the file it hides. Its own line outside the managed block,
+     * disjoint from `capability-excludes`, so neither strips the other's.
+     */
+    {
+      id: "openspec-store-exclude",
+      kind: "merged",
+      path: path.join(".git", "info", "exclude"),
+      scopes: ["session", "wrap"],
+      write: async (input) =>
+        (await reconcileStorePointerExclude(input.repoPath)) ? "written" : "current",
+      degradable: true,
+      removal: { by: "self", remove: (input) => removeStorePointerExclude(input.repoPath) },
+      present: (repoPath) =>
+        workingRepoCapabilityExcludesPresent(repoPath, [OPENSPEC_POINTER_EXCLUDE]),
+    },
+    /**
+     * Degradable: without it OpenSpec still plans in the companion, it only
+     * names no Working Repository edit root — and the wrapper says so.
+     */
+    {
+      id: "openspec-store-pointer",
+      kind: "owned",
+      path: OPENSPEC_POINTER_PATH,
+      scopes: ["session", "wrap"],
+      write: async (input) =>
+        input.companionPath ? projectStorePointer(input.repoPath, input.companionPath) : "skipped",
+      degradable: true,
+      removal: {
+        by: "self",
+        remove: (input) => removeStorePointer(input.repoPath),
+        retains: "openspec-store-registration",
+      },
+      present: storePointerPresent,
+    },
     {
       id: "claude-skill-links",
       kind: "merged",

package/src/lib/orchestrator/projection-openspec-store.ts

@@ -0,0 +1,164 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { generatedHeader } from "../../runtime/projection";
+import { reconcileWorkingRepoCapabilityExcludes } from "../../tools/setup/working-repo-local-state";
+import { ensureStoreRegistration } from "./openspec-store";
+import type { ProjectionWriteReport, ProjectionWriteState } from "./projection-types";
+
+/**
+ * The store pointer: an `openspec/config.yaml` in the Working Repository that
+ * declares the companion's OpenSpec store. Run from inside the repository,
+ * OpenSpec then plans in the store and names the repository as the edit root.
+ *
+ * The pointer's whole `openspec/` folder is hidden only through
+ * `.git/info/exclude`, never the repository's own `.gitignore`: all planning
+ * lives in the store, so nothing under it belongs to the repository. Mate
+ * never writes it where the repository already owns an OpenSpec root.
+ */
+
+const execFileAsync = promisify(execFile);
+
+export const OPENSPEC_POINTER_PATH = path.join("openspec", "config.yaml");
+/** The exclusion line, outside the managed block so a core-block rewrite keeps it. */
+export const OPENSPEC_POINTER_EXCLUDE = "/openspec/";
+/** The earlier file-only line; still managed so a refresh replaces it. */
+const LEGACY_POINTER_EXCLUDE = "/openspec/config.yaml";
+const MANAGED_POINTER_EXCLUDES = [OPENSPEC_POINTER_EXCLUDE, LEGACY_POINTER_EXCLUDE];
+
+export type StorePointer = { kind: "absent" } | { kind: "foreign" } | { kind: "mate"; id: string };
+
+function pointerFile(repoPath: string): string {
+  return path.join(repoPath, OPENSPEC_POINTER_PATH);
+}
+
+function renderPointer(id: string): string {
+  return `${generatedHeader()}\nstore: ${id}\n`;
+}
+
+async function exists(candidate: string): Promise<boolean> {
+  return fs
+    .access(candidate)
+    .then(() => true)
+    .catch(() => false);
+}
+
+export async function readStorePointer(repoPath: string): Promise<StorePointer> {
+  const content = await fs.readFile(pointerFile(repoPath), "utf8").catch(() => null);
+  if (content === null) return { kind: "absent" };
+  const [first, ...rest] = content.split(/\r?\n/);
+  if (first !== generatedHeader()) return { kind: "foreign" };
+  const store = rest.map((line) => /^store:\s*(\S+)\s*$/.exec(line)?.[1]).find(Boolean);
+  return { kind: "mate", id: store ?? "" };
+}
+
+/**
+ * Why Mate may not point this repository at a store, or `null` when it may: a
+ * config Mate did not write, or a planning root of the repository's own.
+ */
+export async function storePointerIneligibility(repoPath: string): Promise<string | null> {
+  if ((await readStorePointer(repoPath)).kind === "foreign") {
+    return `${pointerFile(repoPath)} is not Mate's`;
+  }
+  for (const dir of ["specs", "changes"]) {
+    const planningRoot = path.join(repoPath, "openspec", dir);
+    // oxlint-disable-next-line no-await-in-loop -- two probes, first hit wins
+    if (await exists(planningRoot)) return `${planningRoot} is the repository's own OpenSpec root`;
+  }
+  return null;
+}
+
+/**
+ * Whether Git would show the pointer, asked of Git itself so a re-including
+ * rule anywhere above the exclude file counts. `null` when the pointer stays
+ * out of every diff, including outside a Git work tree.
+ */
+export async function pointerIgnoreProblem(repoPath: string): Promise<string | null> {
+  const pointer = OPENSPEC_POINTER_PATH.split(path.sep).join("/");
+  try {
+    await execFileAsync("git", ["check-ignore", "-q", pointer], { cwd: repoPath });
+    return null;
+  } catch (error) {
+    if ((error as { code?: unknown }).code !== 1) return null;
+  }
+  const { stdout } = await execFileAsync("git", ["check-ignore", "-v", "-n", pointer], {
+    cwd: repoPath,
+  }).catch(() => ({ stdout: "" }));
+  const [source, line, pattern] = stdout.split("\t")[0]?.split(":") ?? [];
+  return pattern
+    ? `${pointer} is re-included by "${pattern}" (${source}:${line})`
+    : `${pointer} is not ignored by Git`;
+}
+
+async function persistPointer(repoPath: string, id: string): Promise<void> {
+  await fs.mkdir(path.dirname(pointerFile(repoPath)), { recursive: true });
+  await fs.writeFile(pointerFile(repoPath), renderPointer(id), "utf8");
+}
+
+export async function writeStorePointer(
+  repoPath: string,
+  id: string,
+): Promise<"written" | "current"> {
+  const current = await readStorePointer(repoPath);
+  if (current.kind === "mate" && current.id === id) return "current";
+  await persistPointer(repoPath, id);
+  return "written";
+}
+
+/** Only Mate's pointer; `openspec/` goes too when nothing else is left in it. */
+export async function removeStorePointer(repoPath: string): Promise<"removed" | "absent"> {
+  if ((await readStorePointer(repoPath)).kind !== "mate") return "absent";
+  await fs.rm(pointerFile(repoPath));
+  await fs.rmdir(path.dirname(pointerFile(repoPath))).catch(() => {});
+  return "removed";
+}
+
+export async function storePointerPresent(repoPath: string): Promise<boolean> {
+  return (await readStorePointer(repoPath)).kind === "mate";
+}
+
+/** Keeps the exclusion line exactly while the repository may carry Mate's pointer. */
+export async function reconcileStorePointerExclude(repoPath: string): Promise<boolean> {
+  const eligible = (await storePointerIneligibility(repoPath)) === null;
+  return reconcileWorkingRepoCapabilityExcludes(
+    repoPath,
+    eligible ? [OPENSPEC_POINTER_EXCLUDE] : [],
+    MANAGED_POINTER_EXCLUDES,
+  );
+}
+
+export async function removeStorePointerExclude(repoPath: string): Promise<"removed" | "absent"> {
+  return (await reconcileWorkingRepoCapabilityExcludes(repoPath, [], MANAGED_POINTER_EXCLUDES))
+    ? "removed"
+    : "absent";
+}
+
+function pointerNotWritten(reason: string): ProjectionWriteReport {
+  return { state: "skipped", warnings: [`OpenSpec store pointer not written: ${reason}`] };
+}
+
+/**
+ * Eligibility, then registration, then the pointer: a pointer naming a store
+ * OpenSpec cannot resolve would break every root-resolving command. Git is
+ * asked about the pointer only before it is created or rewritten, so a
+ * steady-state refresh spawns nothing.
+ */
+export async function projectStorePointer(
+  repoPath: string,
+  companionPath: string,
+): Promise<ProjectionWriteState | ProjectionWriteReport> {
+  /** A companion without OpenSpec has no store to point at; nothing to say. */
+  if (!(await exists(path.join(companionPath, "openspec")))) return "skipped";
+  const ineligible = await storePointerIneligibility(repoPath);
+  if (ineligible) return pointerNotWritten(ineligible);
+  const registration = await ensureStoreRegistration(companionPath);
+  if (registration.state === "skipped") return pointerNotWritten(registration.reason);
+  const current = await readStorePointer(repoPath);
+  if (current.kind === "mate" && current.id === registration.id) return registration.state;
+  const ignoreProblem = await pointerIgnoreProblem(repoPath);
+  if (ignoreProblem) return pointerNotWritten(ignoreProblem);
+  await persistPointer(repoPath, registration.id);
+  return "written";
+}

package/src/lib/orchestrator/projection-types.ts

@@ -25,6 +25,8 @@ export type ProjectionEntryId =
   | "repo-local-framework"
   | "repo-local-registry"
   | "projection-pair"
+  | "openspec-store-exclude"
+  | "openspec-store-pointer"
   | "claude-skill-links"
   | "workspace-document"
   | "capability-excludes"
@@ -85,6 +87,8 @@ export type ProjectionEntryRemoval =
   | {
       readonly by: "self";
       remove(input: ProjectionRemovalInput): Promise<"removed" | "absent">;
+      /** What removing this path deliberately leaves outside the repository, named in the outcome. */
+      readonly retains?: string;
     }
   | { readonly by: "entry"; readonly entry: ProjectionEntryId }
   | { readonly by: "retained"; readonly because: string };
@@ -130,6 +134,8 @@ export interface ProjectionEntryOutcome {
   warnings?: string[];
   /** Present only when the entry wrote or withdrew paths it reports one by one. */
   changed?: ProjectionChangedPaths;
+  /** Present only on a removal that leaves something outside the repository behind. */
+  retains?: string;
 }
 
 export interface ProjectionResult {
@@ -157,7 +163,7 @@ export interface ProjectionDescription {
   projection: ProjectionFile | null;
 }
 
-/** A degradable entry's failure is reported in the outcomes and nowhere else. */
+/** Skips a degradable entry's failure: it never fails a pass, only shows in the outcomes. */
 export function firstFailure(outcomes: ProjectionEntryOutcome[]): ProjectionEntryOutcome | null {
   return outcomes.find((outcome) => outcome.state === "failed" && !outcome.degradable) ?? null;
 }

package/src/lib/orchestrator/working-repo-projection.ts

@@ -120,7 +120,8 @@ export async function unproject(input: ProjectionRemovalInput): Promise<Projecti
     }
     try {
       // oxlint-disable-next-line no-await-in-loop -- reverse catalogue order is the contract
-      outcomes.push(outcome(entry, await removal.remove(input)));
+      const removed = outcome(entry, await removal.remove(input));
+      outcomes.push(removal.retains ? { ...removed, retains: removal.retains } : removed);
     } catch (error) {
       outcomes.push(outcome(entry, "failed", toError(error)));
     }

package/src/lib/orchestrator/wrap-pass.ts

@@ -124,6 +124,10 @@ export async function runWrapPass(
     warnings: [
       ...rendered.warnings,
       ...result.outcomes.flatMap((outcome) => outcome.warnings ?? []),
+      /** A degradable failure does not fail the pass, but it is never silent. */
+      ...result.outcomes
+        .filter((outcome) => outcome.state === "failed" && outcome.degradable)
+        .map((outcome) => entryFailureMessage(outcome, repository.id)),
     ],
     runtimes,
     wrapState,

package/src/opencode/companion-hooks.ts

@@ -99,6 +99,7 @@ export async function guardToolInput(
   context: CompanionContext,
   tool: string,
   input: unknown,
+  env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   const args = (input ?? {}) as Record<string, unknown>;
   const filePaths =
@@ -113,25 +114,27 @@ export async function guardToolInput(
       throw new Error(buildArtifactError(context, filePath));
     }
     // oxlint-disable-next-line no-await-in-loop -- the first refusal wins
-    await refuseForkedCompanionWrite(context, filePath);
+    await refuseForkedCompanionWrite(context, filePath, env);
   }
 }
 
 /**
  * Registers the companion guardrails on an OpenCode V2 plugin context.
- * The caller resolves `context` and skips this when no companion resolved.
+ * The caller resolves `context` and skips this when no companion resolved;
+ * `env` is the launch environment the caller decided to trust.
  */
 export async function registerCompanionHooks(
   api: Context,
   context: CompanionContext,
+  env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   /**
    * Anything escaping the repair would cost the session every guardrail
    * below to save a synchronization that is optional by design.
    */
-  await repairCompanionGitOnce(context, process.env, api.location.directory).catch(() => []);
+  await repairCompanionGitOnce(context, env, api.location.directory).catch(() => []);
 
   await api.tool.hook("execute.before", (event) =>
-    guardToolInput(context, event.tool, event.input),
+    guardToolInput(context, event.tool, event.input, env),
   );
 }

package/src/opencode/projected-guidance.ts

@@ -1,14 +1,13 @@
 import { buildOpenCodeGuidance } from "../runtime/companion-guidance";
 import { MATE_ENV } from "../runtime/env-names";
-import { hasLaunchEnvironment } from "../runtime/env";
 import { parseGuidanceContent, type MateGuidanceFile } from "../runtime/guidance";
 import { readCompanionPolicy } from "../runtime/policy";
 import { resolveProjection } from "../runtime/projection";
 
 /**
  * `null` guidance with no errors is the inert case — no companion resolves, so
- * the plugin contributes nothing. Errors are startup failures: a managed launch
- * that failed to inject its payload is broken and must say so.
+ * the plugin contributes nothing. Errors are startup failures: a payload that
+ * does not parse, or projected guidance that cannot be built.
  */
 export interface OpenCodeGuidanceResolution {
   guidance: MateGuidanceFile | null;
@@ -26,9 +25,10 @@ export interface OpenCodeGuidanceResolution {
  * means a Capability toggled after a wrap changes the guidance on the next
  * session with no re-wrap.
  *
- * A missing payload while a launch environment *is* present stays a hard error.
- * That combination means a managed launch failed to inject, which the projection
- * must not paper over.
+ * Without a payload the projection decides, whatever other `MATE_*` variables
+ * `env` carries: those are inherited by every descendant of a Mate session and
+ * do not mark a managed launch. A present but malformed payload stays a hard
+ * error.
  */
 export function resolveOpenCodeGuidance(
   env: Record<string, string | undefined> = process.env,
@@ -40,13 +40,6 @@ export function resolveOpenCodeGuidance(
     return { guidance: errors.length > 0 ? null : guidance, errors };
   }
 
-  if (hasLaunchEnvironment(env)) {
-    return {
-      guidance: null,
-      errors: [`missing ${MATE_ENV.guidanceJson} in the launch environment`],
-    };
-  }
-
   const projection = resolveProjection(cwd);
   if (!projection) return { guidance: null, errors: [] };
 

package/src/runtime/projection.ts

@@ -88,7 +88,7 @@ export function projectionEnvPath(repoRoot: string): string {
   return path.join(repoLocalDirPath(repoRoot), PROJECTION_ENV_FILE);
 }
 
-const generatedHeader = () => `# generated by ${FRAMEWORK_NAME} — do not edit`;
+export const generatedHeader = (): string => `# generated by ${FRAMEWORK_NAME} — do not edit`;
 
 export function renderProjectionYaml(file: ProjectionFile): string {
   const document: Record<string, string> = { stamp: file.stamp };