@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

package/src/tools/setup/providers/opencode.ts

@@ -4,6 +4,17 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { isLegacyMateOpenCodePluginReference } from "../../../lib/opencode-plugin-package";
+import { resolveSecretPolicy } from "../../../runtime/policy";
+import { runtimeOpenCodePluginRoot } from "../../../runtime/runtime-directory";
+import {
+  OPENCODE_CONFIG_DOCUMENT,
+  OPENCODE_MCP_SERVERS_AT,
+  renderedDocument,
+  type ManagedRegion,
+  type RenderedRuntimeDocument,
+  type RenderedRuntimeDocuments,
+} from "../../../runtime/runtime-document-manifest";
+import { projectableSecretDenyPatterns } from "../../../runtime/secret-patterns";
 import { refreshFromTemplate, stripGuidanceBlock } from "../plugins/guidance";
 import { stripSectionFromFile, type RemoveHeadingSectionOptions } from "./agent-file-sections";
 import { reconcileSharedSkillTree } from "./agents-skill-root";
@@ -502,7 +513,7 @@ async function reconcileOpenCodeMcpContributions(
 }
 
 /** The Mate-managed V2 `mcp.servers` map of one pass, as a value. */
-export function renderManagedOpenCodeMcpServers(
+function renderManagedOpenCodeMcpServers(
   contributions: CapabilityContributionInput[] = [],
 ): Record<string, unknown> {
   const servers: Record<string, unknown> = {};
@@ -529,6 +540,174 @@ export function renderCompanionExternalDirectoryPermissions(
   ];
 }
 
+/**
+ * V2 deny rules for the default secret files: `read`, and `edit`, which covers
+ * write and patch. Only patterns that can't match an allow-listed file are
+ * rendered, as for Claude; the middleware enforces the rest of the set.
+ */
+export function renderSecretDenyPermissions(
+  companionPath: string,
+): Array<{ action: string; resource: string; effect: string }> {
+  if (!resolveSecretPolicy(companionPath).guardrails) return [];
+  return projectableSecretDenyPatterns().flatMap((pattern) =>
+    ["read", "edit"].map((action) => ({ action, resource: `**/${pattern}`, effect: "deny" })),
+  );
+}
+
+/**
+ * The working target's OpenCode document, rendered as a value, with the
+ * companion's `.opencode/opencode.json` folded in.
+ *
+ * The Mate plugin root is what makes an Unmanaged OpenCode session load the
+ * companion guidance at all: OpenCode has no config channel for a generated
+ * system prompt, so the plugin is the only injection point. It is named through
+ * the runtime directory, so a reinstall does not strand a wrapped repository.
+ * The managed launch carries no overlay of its own, so this document is the one
+ * place every OpenCode session in the repository loads it from.
+ */
+export async function renderOpenCodeWorkingDocuments(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<RenderedRuntimeDocuments> {
+  const documents = renderedDocument(OPENCODE_CONFIG_DOCUMENT, [
+    {
+      at: ["plugins"],
+      kind: "list",
+      values: [runtimeOpenCodePluginRoot()],
+    },
+    {
+      at: [...OPENCODE_MCP_SERVERS_AT],
+      kind: "map",
+      entries: renderManagedOpenCodeMcpServers(inputs),
+    },
+    {
+      at: ["permissions"],
+      kind: "list",
+      values: [
+        ...renderCompanionExternalDirectoryPermissions(ctx.companionPath),
+        ...renderSecretDenyPermissions(ctx.companionPath),
+      ],
+    },
+    {
+      at: ["skills"],
+      kind: "list",
+      values: [path.join(ctx.companionPath, ".agents", "skills")],
+    },
+    { at: ["references"], kind: "map", entries: { mate: ctx.companionPath } },
+  ]);
+  if (ctx.target !== "working") return { documents, warnings: [] };
+  return mergeCompanionOpenCodeConfig(ctx.companionPath, documents);
+}
+
+/** Keys Mate renders its own regions for; the companion's values join those regions. */
+const MATE_OPENCODE_KEYS = new Set(["plugins", "permissions", "skills", "mcp", "references"]);
+
+function relativePathValues(value: unknown, at: string[]): string[] {
+  if (typeof value === "string") {
+    return value.startsWith("./") || value.startsWith("../") ? [at.join(".")] : [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) => relativePathValues(entry, [...at, String(index)]));
+  }
+  if (isRecord(value)) {
+    return Object.entries(value).flatMap(([key, entry]) => relativePathValues(entry, [...at, key]));
+  }
+  return [];
+}
+
+/** Replaces the region at `at` with what `merge` builds from it, or appends one. */
+function upsertRegion(
+  regions: ManagedRegion[],
+  at: string[],
+  merge: (found: ManagedRegion | undefined) => ManagedRegion,
+): void {
+  const key = JSON.stringify(at);
+  const index = regions.findIndex((region) => JSON.stringify(region.at) === key);
+  if (index === -1) regions.push(merge(undefined));
+  else regions[index] = merge(regions[index]);
+}
+
+/** Mate's own values stay; companion values it does not already list go first. */
+function mergeListRegion(regions: ManagedRegion[], at: string[], extra: unknown[]): void {
+  upsertRegion(regions, at, (found) => {
+    const own = found?.kind === "list" ? found.values : [];
+    const seen = new Set(own.map((value) => JSON.stringify(value)));
+    const values = [...extra.filter((value) => !seen.has(JSON.stringify(value))), ...own];
+    return { at, kind: "list", values };
+  });
+}
+
+/** Mate's own entries win over companion entries of the same name. */
+function mergeMapRegion(
+  regions: ManagedRegion[],
+  at: string[],
+  extra: Record<string, unknown>,
+): void {
+  upsertRegion(regions, at, (found) => {
+    const own = found?.kind === "map" ? found.entries : {};
+    return { at, kind: "map", entries: { ...extra, ...own } };
+  });
+}
+
+/** Relative reference paths resolved against the companion's `.opencode/`. */
+function resolveReferences(
+  references: Record<string, unknown>,
+  companionDir: string,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(references).map(([name, reference]) => [
+      name,
+      typeof reference === "string" && !path.isAbsolute(reference)
+        ? path.resolve(companionDir, reference)
+        : reference,
+    ]),
+  );
+}
+
+/**
+ * Folds the companion's `.opencode/opencode.json` into the wrapped document.
+ * Mate's regions beat companion values; other top-level keys yield to the
+ * repository's. `references` resolve against the companion's `.opencode/`;
+ * other relative paths are reported, not rewritten.
+ */
+async function mergeCompanionOpenCodeConfig(
+  companionPath: string,
+  documents: RenderedRuntimeDocument[],
+): Promise<RenderedRuntimeDocuments> {
+  const [rendered] = documents;
+  const companionConfigPath = path.join(companionPath, ".opencode", "opencode.json");
+  const companion = rendered ? await readOpenCodeConfig(companionConfigPath) : null;
+  if (!rendered || !companion?.present) return { documents, warnings: [] };
+
+  const regions = [...rendered.regions] as ManagedRegion[];
+  const warnings: string[] = [];
+
+  const companionDir = path.dirname(companionConfigPath);
+  for (const [key, value] of Object.entries(companion.config)) {
+    if (key === "$schema") continue;
+    if (key === "references" && isRecord(value)) {
+      mergeMapRegion(regions, ["references"], resolveReferences(value, companionDir));
+      continue;
+    }
+    for (const at of relativePathValues(value, [key])) {
+      warnings.push(
+        `${companionConfigPath}: ${at} is a relative path, which resolves against the working repository once merged into ${OPENCODE_CONFIG_DOCUMENT}; use an absolute path.`,
+      );
+    }
+    if (MATE_OPENCODE_KEYS.has(key)) {
+      if (key === "mcp" && isRecord(value) && isRecord(value.servers)) {
+        mergeMapRegion(regions, [...OPENCODE_MCP_SERVERS_AT], value.servers);
+      } else if (Array.isArray(value)) {
+        mergeListRegion(regions, [key], value);
+      }
+      continue;
+    }
+    regions.push({ at: [key], kind: "value", value, yields: true });
+  }
+
+  return { documents: [{ path: OPENCODE_CONFIG_DOCUMENT, regions }], warnings };
+}
+
 /**
  * Reconcile declared agent definition files under `.opencode/agents/`. Runs
  * in both companion and hub scope — an agent definition is fully

package/src/tools/setup/utils.ts

@@ -65,21 +65,31 @@ function waitForClose(child: ChildProcess, formatError: (code: number) => string
   });
 }
 
+export interface RunCommandOptions {
+  cwd?: string;
+  /** Merged over `process.env` for the child only; Mate's own env is untouched. */
+  env?: Record<string, string>;
+}
+
+function childEnv(options: RunCommandOptions): { env?: NodeJS.ProcessEnv } {
+  return options.env ? { env: { ...process.env, ...options.env } } : {};
+}
+
 export async function runCommand(
   command: string,
   args: string[],
-  options: { cwd?: string } = {},
+  options: RunCommandOptions = {},
 ): Promise<void> {
-  const child = spawn(command, args, { cwd: options.cwd, stdio: "inherit" });
+  const child = spawn(command, args, { cwd: options.cwd, stdio: "inherit", ...childEnv(options) });
   await waitForClose(child, (code) => `${command} ${args.join(" ")} exited with code ${code}`);
 }
 
 export async function runCommandSilently(
   command: string,
   args: string[],
-  options: { cwd?: string } = {},
+  options: RunCommandOptions = {},
 ): Promise<void> {
-  const child = spawn(command, args, { cwd: options.cwd, stdio: "pipe" });
+  const child = spawn(command, args, { cwd: options.cwd, stdio: "pipe", ...childEnv(options) });
   await waitForClose(child, (code) => `${command} ${args.join(" ")} exited with code ${code}`);
 }
 

package/src/tools/setup.ts

@@ -18,11 +18,25 @@ import {
   type CapabilityConfig,
   type FrameworkConfig,
 } from "../lib/orchestrator/types";
+import { getClaudePluginRoot } from "../lib/package-paths";
+import type { RenderedRuntimeDocuments } from "../runtime/runtime-document-manifest";
 import {
   collectManagedGitignoreEntries,
   writeManagedGitignoreBlock,
 } from "./setup/plugins/gitignore";
-import type { PluginRegistration, SetupContext, SetupScope } from "./setup/plugin";
+import { createManagedOutputCollector } from "./setup/managed-output";
+import type {
+  ManagedOutputReport,
+  PluginRegistration,
+  SetupContext,
+  SetupScope,
+} from "./setup/plugin";
+import {
+  inspectClaudePluginFolders,
+  type ClaudePluginContributionFailure,
+  type ClaudePluginDirectoryReport,
+  type ClaudePluginFolders,
+} from "./setup/providers/claude-plugin-folders";
 import { getActiveDistribution } from "../distribution";
 import { createUvPlugin } from "./setup/package-managers/uv";
 import type { PackageManagerSetupDeps } from "./setup/package-managers/uv";
@@ -38,10 +52,12 @@ import { hydrateDynamicPlugins } from "./setup/dynamic-plugins/hydrate";
 import { installDeclaredPlugins } from "./setup/dynamic-plugins/install";
 import {
   buildSetupInstallationPlan,
+  collectRuntimeContributionInputs,
   executeSetupInstallationPlan,
+  publishRuntimeClaudePluginMarketplaces,
   renderRuntimeDocuments,
-  type RenderedRuntimeDocuments,
   type SetupInstallationOutcome,
+  type SetupInstallationPlan,
 } from "./setup/engine";
 
 export interface SetupInput {
@@ -57,6 +73,16 @@ export interface SetupDependencies {
   globalConfigStore?: GlobalConfigStore;
 }
 
+export interface CompanionSyncOptions {
+  /** Regenerates OpenSpec CLI output; set only by `mate companion update`. */
+  regenerateOpenSpec?: boolean;
+}
+
+export interface CompanionSyncOutcome extends SetupInstallationOutcome {
+  /** The managed output this pass wrote or removed. */
+  managedOutput: ManagedOutputReport;
+}
+
 export async function applySetupCompatibilities(
   companionPath: string,
   config: FrameworkConfig,
@@ -64,11 +90,23 @@ export async function applySetupCompatibilities(
   plugins: PluginRegistration[] = getActiveDistribution().registry.getEntries(),
   repoPath?: string,
   scope: SetupScope = config.type === "hub" ? "hub" : "companion",
-): Promise<SetupInstallationOutcome> {
+  options: CompanionSyncOptions = {},
+): Promise<CompanionSyncOutcome> {
   const plan = buildSetupInstallationPlan(config, plugins);
   const activeProviders = plan.activeProviders;
-  const ctx: SetupContext = { companionPath, config, mode, activeProviders, repoPath, scope };
-  return executeSetupInstallationPlan(ctx, plugins, plan);
+  const managedOutput = createManagedOutputCollector(companionPath);
+  const ctx: SetupContext = {
+    companionPath,
+    config,
+    mode,
+    activeProviders,
+    repoPath,
+    scope,
+    ...(options.regenerateOpenSpec ? { regenerateOpenSpec: true } : {}),
+    managedOutput: managedOutput.recorder,
+  };
+  const outcome = await executeSetupInstallationPlan(ctx, plugins, plan);
+  return { ...outcome, managedOutput: managedOutput.report() };
 }
 
 /**
@@ -82,16 +120,83 @@ export async function renderWorkingRuntimeDocuments(
   repoPath: string,
   plugins: PluginRegistration[] = getActiveDistribution().registry.getAll(),
 ): Promise<RenderedRuntimeDocuments> {
+  const { plan, ctx } = planSyncPass(companionPath, config, plugins, {
+    repoPath,
+    target: "working",
+  });
+  return renderRuntimeDocuments(ctx, plugins, plan);
+}
+
+/**
+ * Publishes the enabled Claude plugin folders for a Working Repository's wrap
+ * pass, before it renders; see {@link publishRuntimeClaudePluginMarketplaces}.
+ */
+export async function publishWorkingClaudePluginMarketplaces(
+  companionPath: string,
+  config: FrameworkConfig,
+  repoPath: string,
+  plugins: PluginRegistration[] = getActiveDistribution().registry.getAll(),
+): Promise<ClaudePluginFolders> {
+  const { plan, ctx } = planSyncPass(companionPath, config, plugins, {
+    repoPath,
+    target: "working",
+  });
+  return publishRuntimeClaudePluginMarketplaces(ctx, plugins, plan);
+}
+
+/** A sync pass's plan and context, for a caller that runs no plugin phase. */
+function planSyncPass(
+  companionPath: string,
+  config: FrameworkConfig,
+  plugins: PluginRegistration[],
+  extra: Pick<SetupContext, "repoPath" | "target"> = {},
+): { plan: SetupInstallationPlan; ctx: SetupContext } {
   const plan = buildSetupInstallationPlan(config, plugins);
   const ctx: SetupContext = {
     companionPath,
     config,
     mode: "sync",
     activeProviders: plan.activeProviders,
-    repoPath,
-    target: "working",
+    ...extra,
+  };
+  return { plan, ctx };
+}
+
+/** What an operator sees of the enabled Capabilities' Claude plugin folders. */
+export interface ClaudePluginDirectoryInspection {
+  plugins: ClaudePluginDirectoryReport[];
+  /** Capabilities whose contributions rejected; the other Capabilities are still listed. */
+  failures: ClaudePluginContributionFailure[];
+}
+
+/**
+ * Enabled Capabilities' declared Claude plugin folders and whether `mate claude`
+ * passes each, checked against the running install's bundled plugin. Read-only:
+ * runs no plugin phase and reconciles nothing.
+ */
+export async function inspectClaudePluginDirectories(
+  companionPath: string,
+  config: FrameworkConfig,
+  plugins: PluginRegistration[] = getActiveDistribution().registry.getEntries(),
+): Promise<ClaudePluginDirectoryInspection> {
+  const { plan, ctx } = planSyncPass(companionPath, config, plugins);
+  const failures: ClaudePluginContributionFailure[] = [];
+  const inputs = await collectRuntimeContributionInputs(ctx, plugins, plan, (capability, error) =>
+    failures.push({
+      capability,
+      reason: error instanceof Error ? error.message : String(error),
+    }),
+  );
+  return {
+    plugins: [
+      ...(
+        await inspectClaudePluginFolders(inputs.get("claude") ?? [], {
+          bundledPluginRoot: getClaudePluginRoot(),
+        })
+      ).report,
+    ],
+    failures,
   };
-  return renderRuntimeDocuments(ctx, plugins, plan);
 }
 
 export async function updateProjectGitignore(
@@ -104,18 +209,29 @@ export async function updateProjectGitignore(
   await writeManagedGitignoreBlock(path.join(companionPath, ".gitignore"), FRAMEWORK_NAME, entries);
 }
 
+export interface CompanionSyncResult {
+  /** For a launch to pass and report; every other caller ignores them. */
+  claudePluginFolders: ClaudePluginFolders;
+  /** For `mate companion update` to sort changed paths; a launch ignores it. */
+  managedOutput: ManagedOutputReport;
+}
+
 export async function syncCompanionFiles(
   companionPath: string,
   config: FrameworkConfig,
   repoPath?: string,
-): Promise<void> {
-  await applySetupCompatibilities(
+  options: CompanionSyncOptions = {},
+): Promise<CompanionSyncResult> {
+  const outcome = await applySetupCompatibilities(
     companionPath,
     config,
     "sync",
     getActiveDistribution().registry.getAll(),
     repoPath,
+    undefined,
+    options,
   );
+  return { claudePluginFolders: outcome.claudePluginFolders, managedOutput: outcome.managedOutput };
 }
 
 export const setupToolDeps = {

package/wrappers/bin/graphify

@@ -69,6 +69,34 @@ _graphify_root="$(dirname "$_graphify_out")"
 _graph_json="$_graphify_out/graph.json"
 export GRAPHIFY_OUT="$_graphify_out"
 
+# Secret gate: leaves secret files out of every extraction and prunes any
+# secret that still reaches the output. It never stops graphify: when the gate
+# can't run, the wrapper warns and runs graphify anyway.
+_gate="$_this_dir/../lib/graphify-gate.mjs"
+_secret_excludes=()
+_secret_pre() {
+  local _out _p
+  if ! _out="$(node "$_gate" pre "$_companion" "$_repo_path")"; then
+    echo "graphify: warning: the secret gate did not run; secret files may be indexed" >&2
+    return
+  fi
+  while IFS= read -r _p; do
+    [ -n "$_p" ] && _secret_excludes+=(--exclude "$_p")
+  done <<< "$_out"
+}
+_secret_post() {
+  node "$_gate" post "$_companion" "$_graphify_out" ||
+    echo "graphify: warning: the graphify output was not checked for secrets" >&2
+}
+# Runs an extraction that accepts --exclude, then prunes its output.
+_extract() {
+  _secret_pre
+  "$_real" "$@" "${_secret_excludes[@]}"
+  local _status=$?
+  _secret_post
+  exit "$_status"
+}
+
 _cmd="${1:-}"
 case "$_cmd" in
   build)
@@ -81,16 +109,32 @@ case "$_cmd" in
         *) _rest+=("$_a") ;;
       esac
     done
-    exec "$_real" extract "$_repo_path" --out "$_graphify_root" "${_rest[@]}"
+    _extract extract "$_repo_path" --out "$_graphify_root" "${_rest[@]}"
     ;;
   update)
     if [ "$#" -eq 1 ] || [[ "$2" == -* ]]; then
-      exec "$_real" "$_repo_path" --update "${@:2}"
+      _extract "$_repo_path" --update "${@:2}"
+    else
+      _extract "$2" --update "${@:3}"
+    fi
+    ;;
+  extract)
+    if [ "$#" -eq 1 ] || [[ "$2" == -* ]]; then
+      _extract extract "$_repo_path" "${@:2}"
+    else
+      _extract "$@"
+    fi
+    ;;
+  watch)
+    # Long-running: only the ignore region applies; there is no output to prune.
+    _secret_pre
+    if [ "$#" -eq 1 ] || [[ "$2" == -* ]]; then
+      exec "$_real" watch "$_repo_path" "${@:2}"
     else
-      exec "$_real" "$2" --update "${@:3}"
+      exec "$_real" "$@"
     fi
     ;;
-  extract|watch|cluster-only|label|check-update)
+  cluster-only|label|check-update)
     if [ "$#" -eq 1 ] || [[ "$2" == -* ]]; then
       exec "$_real" "$_cmd" "$_repo_path" "${@:2}"
     else
@@ -120,6 +164,10 @@ case "$_cmd" in
     fi
     ;;
   *)
+    # A direct `graphify <path> --update` is an extraction too.
+    for _a in "$@"; do
+      [ "$_a" = "--update" ] && _extract "$@"
+    done
     exec "$_real" "$@"
     ;;
 esac

package/wrappers/bin/openspec

@@ -50,16 +50,25 @@ if [ -z "$_companion" ]; then
 fi
 [ -n "$_companion" ] || { echo "openspec: no mate context here — run \`mate wrap\` in this repository" >&2; exit 1; }
 
+# The OpenSpec CLI Mate ships with, found the way Node resolves it: upward from
+# the package root, hoisted or nested under mate-core (distribution packages).
+# Never an openspec on PATH, so a global install of another version is ignored.
+# Physical path: the runtime directory reaches wrappers/ through a symlink.
 _real=""
-IFS=:
-for _dir in $PATH; do
-    [ "$_dir" = "$_this_dir" ] && continue
-    [ -x "$_dir/openspec" ] || continue
-    _real="$_dir/openspec"
-    break
+_dir="$(cd -P "$_this_dir" && cd ../.. && pwd -P)"
+while [ -z "$_real" ]; do
+  for _candidate in \
+    "$_dir/node_modules/@fission-ai/openspec/bin/openspec.js" \
+    "$_dir/node_modules/@uniqbit/mate-core/node_modules/@fission-ai/openspec/bin/openspec.js"; do
+    if [ -f "$_candidate" ]; then
+      _real="$_candidate"
+      break 2
+    fi
+  done
+  [ "$_dir" = "/" ] && break
+  _dir="$(dirname "$_dir")"
 done
-unset IFS
-[ -n "$_real" ] || { echo "openspec wrapper: real binary not found in PATH" >&2; exit 1; }
+[ -n "$_real" ] || { echo "openspec: bundled OpenSpec CLI is missing. Reinstall Mate to restore it." >&2; exit 1; }
 command="${1-}"
 if [ "$command" = "templates" ]; then
   has_schema=0
@@ -133,4 +142,19 @@ case "$command" in
     _mate_use_store_pointer
     ;;
 esac
-exec env -C "$_cwd" "$_real" "$@"
+# A JS entry's `#!/usr/bin/env node` shebang needs an executable bit and `node`
+# on PATH; without either (Bun-only installs) it runs on an explicit runtime.
+_shebang=""
+[ "${_real%.js}" != "$_real" ] && { IFS= read -r _shebang < "$_real" || true; }
+if [ -n "$_shebang" ] && {
+  [ ! -x "$_real" ] ||
+    { [ "$_shebang" = "#!/usr/bin/env node" ] && ! command -v node >/dev/null 2>&1; }
+}; then
+  _runtime="$(command -v node || command -v bun || true)"
+  [ -n "$_runtime" ] || { echo "openspec: neither node nor bun is on PATH to run $_real" >&2; exit 1; }
+  set -- "$_real" "$@"
+  _real="$_runtime"
+fi
+# Mate decides the OpenSpec version, so OpenSpec's update hint is wrong advice
+# here; both variables reach the delegated binary only.
+exec env -C "$_cwd" OPENSPEC_TELEMETRY=0 OPENSPEC_NO_UPDATE_CHECK=1 "$_real" "$@"

package/wrappers/lib/graphify-gate.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Thin shim: the gate lives in src/tools/setup/capabilities/graphify-gate.ts,
+// loaded through the plugin's ts-loader because the installed package sits
+// inside node_modules where node's native type stripping is disabled.
+import "../../claude-plugin/hooks/ts-loader.mjs";
+
+const { runGraphifyGate } = await import("../../src/tools/setup/capabilities/graphify-gate.ts");
+process.exitCode = await runGraphifyGate(process.argv.slice(2));