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

package/src/cli/commands/cap/graphify.ts

@@ -4,10 +4,16 @@ import path from "node:path";
 
 import { resolveForCapability } from "../../../lib/orchestrator/framework-context";
 import type { CapabilityConfig } from "../../../lib/orchestrator/types";
+import { resolveSecretPolicy } from "../../../runtime/policy";
 import {
   GRAPHIFY_OUTPUT_SUBDIR,
   GRAPHIFY_STORE_SEGMENT,
 } from "../../../tools/setup/capabilities/graphify";
+import {
+  ensureGraphifySecretExclusion,
+  graphifySecretExcludeArgs,
+  pruneGraphifySecrets,
+} from "../../../tools/setup/capabilities/graphify-secrets";
 import { ensureUnambiguousCompanion } from "../shared/companion-selection";
 
 export interface GraphifyPaths {
@@ -17,6 +23,23 @@ export interface GraphifyPaths {
 
 export interface GraphifyCapDeps {
   ensureUnambiguousCompanion?: (cwd: string) => Promise<boolean>;
+  resolveForCapability?: typeof resolveForCapability;
+  spawn?: typeof spawnSync;
+}
+
+/** Subcommands that read the source tree into the graph; `update` also runs as `<path> --update`. */
+const GRAPHIFY_EXTRACTION_COMMANDS = new Set(["extract", "update", "watch"]);
+
+export function isGraphifyExtraction(commandArgs: string[]): boolean {
+  return GRAPHIFY_EXTRACTION_COMMANDS.has(commandArgs[0] ?? "") || commandArgs.includes("--update");
+}
+
+/** `extract` and `<path> --update` take `--exclude`; the `update` subcommand rejects it. */
+function acceptsExcludeArgs(commandArgs: string[]): boolean {
+  return (
+    commandArgs[0] === "extract" ||
+    (commandArgs[0] !== "update" && commandArgs.includes("--update"))
+  );
 }
 
 const GRAPHIFY_PATH_COMMANDS = new Set([
@@ -142,8 +165,11 @@ export async function runGraphifyCapCommand(
     return;
   }
 
-  const { companionPath, repositoryId, repository, configStore, workingRepoStore } =
-    await resolveForCapability(process.cwd());
+  const resolve = deps.resolveForCapability ?? resolveForCapability;
+  const spawn = deps.spawn ?? spawnSync;
+  const { companionPath, repositoryId, repository, configStore, workingRepoStore } = await resolve(
+    process.cwd(),
+  );
   const config = await configStore.load();
 
   const capability = (config.capabilities ?? []).find(
@@ -166,11 +192,28 @@ export async function runGraphifyCapCommand(
   const paths = deriveGraphifyPaths(companionPath, repositoryId);
   const commandArgs = deriveGraphifyCommandArgs(args, repo.path, paths);
 
+  /**
+   * Every extraction Mate runs leaves secrets out without stopping: the
+   * `.graphifyignore` region is rewritten, `--exclude` is passed where graphify
+   * takes it, and afterwards any secret that still reached the output is
+   * pruned from it. A step that can't run is a warning, never a refusal.
+   */
+  const extraction = isGraphifyExtraction(commandArgs);
+  const secrets = resolveSecretPolicy(companionPath);
+  if (extraction) {
+    try {
+      await ensureGraphifySecretExclusion(repo.path, secrets);
+    } catch (error) {
+      process.stderr.write(`mate: graphify: warning: ${(error as Error).message}\n`);
+    }
+    if (acceptsExcludeArgs(commandArgs)) commandArgs.push(...graphifySecretExcludeArgs(secrets));
+  }
+
   if (commandArgs[0] === "extract") {
     await fs.mkdir(paths.graphifyOut, { recursive: true });
   }
 
-  const result = spawnSync("graphify", commandArgs, {
+  const result = spawn("graphify", commandArgs, {
     stdio: "inherit",
     env: {
       ...process.env,
@@ -186,4 +229,10 @@ export async function runGraphifyCapCommand(
   if (result.status !== null) {
     process.exitCode = result.status;
   }
+
+  if (extraction && commandArgs[0] !== "watch") {
+    for (const note of await pruneGraphifySecrets(paths.graphifyOut, secrets)) {
+      process.stderr.write(`mate: graphify: ${note}\n`);
+    }
+  }
 }

package/src/cli/commands/cap/index-cmd.ts

@@ -3,6 +3,7 @@ import {
   hasTokensaveCapability,
 } from "../../../lib/orchestrator/capabilities";
 import { resolveForCapability } from "../../../lib/orchestrator/framework-context";
+import { resolveSecretPolicy } from "../../../runtime/policy";
 import type { CapabilityConfig } from "../../../lib/orchestrator/types";
 import {
   ensureTokensaveBranchingPosture,
@@ -29,6 +30,12 @@ export interface SyncCapDeps {
   onStepDone?: (step: SyncCapStep, ok: boolean) => void;
 }
 
+/** The companion's live secret policy decides the secret-file excludes. */
+async function defaultEnsureBranchingPosture(repoPath: string): Promise<void> {
+  const { companionPath } = await resolveForCapability(process.cwd());
+  await ensureTokensaveBranchingPosture(repoPath, resolveSecretPolicy(companionPath));
+}
+
 async function defaultLoadCapabilities(): Promise<CapabilityConfig[]> {
   const { configStore } = await resolveForCapability(process.cwd());
   const config = await configStore.load();
@@ -116,7 +123,7 @@ export async function runIndexCapCommand(args: string[], deps: SyncCapDeps = {})
   const isTokensaveInitialized = deps.isTokensaveInitialized ?? defaultIsTokensaveInitialized;
   const ensureStoreExcluded = deps.ensureTokensaveStoreExcluded ?? ensureTokensaveStoreExcluded;
   const ensureBranchingPosture =
-    deps.ensureTokensaveBranchingPosture ?? ensureTokensaveBranchingPosture;
+    deps.ensureTokensaveBranchingPosture ?? defaultEnsureBranchingPosture;
   const runGraphify = deps.runGraphify ?? runGraphifyCapCommand;
   const runTokensave = deps.runTokensave ?? runTokensaveCapCommand;
 

package/src/cli/commands/cap/openspec.ts

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 
@@ -6,11 +5,13 @@ import { parse } from "yaml";
 
 import { resolveForCapability } from "../../../lib/orchestrator/framework-context";
 import { getEffectiveCliTools } from "../../../lib/orchestrator/setup-compatibilities";
+import { runOpenSpec, type RunOpenSpec } from "../../../lib/openspec-cli";
 import type { CapabilityConfig } from "../../../lib/orchestrator/types";
 import { ensureUnambiguousCompanion } from "../shared/companion-selection";
 
 export interface OpenspecCapDeps {
   ensureUnambiguousCompanion?: (cwd: string) => Promise<boolean>;
+  runOpenSpec?: RunOpenSpec;
 }
 
 export function readOpenSpecProjectSchema(companionPath: string): string | undefined {
@@ -79,33 +80,20 @@ export async function runOpenspecCapCommand(
     readOpenSpecProjectSchema(companionPath),
   );
 
+  const run = deps.runOpenSpec ?? runOpenSpec;
+  const options = { cwd, stdio: "inherit" } as const;
+
   if (forwardedArgs[0] === "init" || forwardedArgs[0] === "update") {
-    const reset = spawnSync("openspec", ["config", "reset", "--all", "-y"], {
-      cwd,
-      stdio: "inherit",
-    });
-    if (reset.error) {
-      process.stderr.write(`Failed to reset openspec config: ${reset.error.message}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    if (reset.status !== 0) {
-      process.exitCode = reset.status ?? 1;
+    const reset = await run(["config", "reset", "--all", "-y"], options);
+    if (reset.code !== 0) {
+      // Inherited output already reached the terminal; only Mate's own message is returned.
+      if (reset.stderr) process.stderr.write(`${reset.stderr}\n`);
+      process.exitCode = reset.code ?? 1;
       return;
     }
   }
 
-  const result = spawnSync("openspec", forwardedArgs, {
-    cwd,
-    stdio: "inherit",
-  });
-  if (result.error) {
-    process.stderr.write(`Failed to run openspec: ${result.error.message}\n`);
-    process.exitCode = 1;
-    return;
-  }
-
-  if (result.status !== null) {
-    process.exitCode = result.status;
-  }
+  const result = await run(forwardedArgs, options);
+  if (result.stderr) process.stderr.write(`${result.stderr}\n`);
+  if (result.code !== null) process.exitCode = result.code;
 }

package/src/cli/commands/companion/open.ts

@@ -1,55 +1,72 @@
-import { CompanionStore } from "../../../lib/orchestrator/repository-link";
-import { resolveForLaunch } from "../../../lib/orchestrator/framework-context";
+import path from "node:path";
+
+import {
+  CompanionResolver,
+  type CompanionMatch,
+  findRepoLocalRegistryFile,
+} from "../../../lib/orchestrator/repository-link";
+import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import { injectEditorFolder, getPreferredEditorCli } from "../../../lib/orchestrator/editor";
-import { ensureUnambiguousCompanion } from "../launch/shared";
+import { WorkingRepoRequiredError } from "../../../lib/orchestrator/types";
+import { resolveProjection } from "../../../runtime/projection";
 
 export const workspaceOpenCommandDeps = {
-  ensureUnambiguousCompanion: () => ensureUnambiguousCompanion(),
-  resolveLaunchContext: () => resolveForLaunch(process.cwd()),
-  createStore: (
-    companionPath: ConstructorParameters<typeof CompanionStore>[0],
-    workingRepoStore: ConstructorParameters<typeof CompanionStore>[1],
-  ) => new CompanionStore(companionPath, workingRepoStore),
+  cwd: () => process.cwd(),
+  /**
+   * The repo-local registry root, or the resolved cwd when there is none: the
+   * global scan only matches a Working Repository on exact path equality.
+   */
+  findRepoRoot: async (cwd: string): Promise<string> =>
+    (await findRepoLocalRegistryFile(cwd))?.repoRoot ?? path.resolve(cwd),
+  /**
+   * Every Linked Companion. Not `launchAmbiguityDeps.resolveLinkedCompanions`:
+   * `logFailures` warns about each stale pointer the resolver drops, which
+   * `wrap` and `session prepare` must not print.
+   */
+  resolveCompanions: async (cwd: string): Promise<CompanionMatch[]> => {
+    const { match, ambiguousMatches } = await new CompanionResolver(
+      new GlobalConfigStore(),
+    ).resolveWithDiagnostics(cwd, { logFailures: true });
+    if (ambiguousMatches.length > 0) return ambiguousMatches;
+    return match ? [match] : [];
+  },
+  resolveProjection,
   getPreferredEditorCli: () => getPreferredEditorCli(),
   injectEditorFolder,
 };
 
+/**
+ * The projected companion first when it still links the repository, then the
+ * rest by resolved path, so repeated runs write an identical workspace file.
+ */
+function orderCompanionPaths(cwd: string, matches: CompanionMatch[]): string[] {
+  const linked = [...new Set(matches.map((match) => path.resolve(match.companionPath)))].toSorted();
+  const projectedPath = workspaceOpenCommandDeps.resolveProjection(cwd)?.companionPath;
+  const projected = projectedPath ? path.resolve(projectedPath) : null;
+  if (!projected || !linked.includes(projected)) return linked;
+  return [projected, ...linked.filter((companionPath) => companionPath !== projected)];
+}
+
 /**
  * @command mate companion open
- * @description Updates the managed `.mate/workspace.code-workspace` file for
- * the active working repository and companion, then adds both folders to the
- * current editor window via `--add`.
- * @remarks Throws if the active repository (from `MATE_REPO_ID`) isn't found
- * in the registry; sets a non-zero exit code if the editor CLI is unavailable,
- * or if the working repo is linked from multiple companions and the ambiguity
- * can't be resolved (see {@link ensureUnambiguousCompanion}).
+ * @description Updates the managed `.mate/workspace.code-workspace` file with
+ * the active working repository and every Linked Companion, then adds those
+ * folders to the current editor window via `--add`.
+ * @remarks Never selects a companion: no picker, no `MATE_ARTIFACT_PATH`
+ * narrowing, and the companion recorded at the Projection Root is left as it
+ * was. Stale companion pointers are skipped with a stderr warning. Throws
+ * {@link WorkingRepoRequiredError} when no existing Linked Companion remains;
+ * sets a non-zero exit code if the editor CLI is unavailable.
  */
 export async function runWorkspaceOpenCommand(): Promise<void> {
-  const unambiguous = await workspaceOpenCommandDeps.ensureUnambiguousCompanion();
-  if (!unambiguous) {
-    process.exitCode = 1;
-    return;
-  }
-
-  const {
-    companionPath,
-    repositoryId,
-    repository: localRepository,
-    workingRepoStore,
-  } = await workspaceOpenCommandDeps.resolveLaunchContext();
-  const repository =
-    localRepository ??
-    (await workspaceOpenCommandDeps
-      .createStore(companionPath, workingRepoStore)
-      .getRepository(repositoryId));
-
-  if (!repository) {
-    throw new Error(`Linked repository not found: ${repositoryId}`);
-  }
+  const cwd = workspaceOpenCommandDeps.cwd();
+  const matches = await workspaceOpenCommandDeps.resolveCompanions(cwd);
+  if (matches.length === 0) throw new WorkingRepoRequiredError("companion open");
 
+  const repoPath = await workspaceOpenCommandDeps.findRepoRoot(cwd);
   const injected = await workspaceOpenCommandDeps.injectEditorFolder(
-    companionPath,
-    repository.path,
+    orderCompanionPaths(cwd, matches),
+    repoPath,
     workspaceOpenCommandDeps.getPreferredEditorCli(),
   );
 

package/src/cli/commands/companion/update.ts

@@ -4,6 +4,10 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { ConfigStore } from "../../../lib/orchestrator/config-store";
+import {
+  refreshWorkingClaudeLinks,
+  type LinkRefreshResult,
+} from "../../../lib/orchestrator/refresh-working-claude-links";
 import type { FrameworkConfig } from "../../../lib/orchestrator/types";
 import { YamlFileStore } from "../../../lib/orchestrator/yaml-file-store";
 import {
@@ -13,12 +17,13 @@ import {
   isNewer,
 } from "../../../lib/update-checker";
 import { resolveCompanionRuntime } from "../../../runtime/env";
-import { syncCompanionFiles } from "../../../tools/setup";
-import { MANAGED_MATE_SKILL_NAMES } from "../../../tools/setup/mate";
+import { syncCompanionFiles, type CompanionSyncOptions } from "../../../tools/setup";
+import type { ManagedOutputOwner, ManagedOutputReport } from "../../../tools/setup/plugin";
 import { runCommand } from "../../../tools/setup/utils";
 import { confirm } from "../../confirm";
 import { defaultGitOps, type GitOps } from "../artifact/finish/git";
 import { resolveCompanionPath } from "./tui";
+import { errorMessage } from "../../../runtime/error-message";
 
 /** Snapshot marker for a changed path that no longer exists on disk. */
 export const DELETED = "<deleted>";
@@ -26,27 +31,17 @@ export const DELETED = "<deleted>";
 const SKILLS_LOCKFILE = "skills-lock.json";
 
 /**
- * OpenSpec CLI output (skills and opsx commands): fully regenerated by every update, so
- * pre-existing uncommitted edits there are stale output, never local work worth separating.
+ * The side the sync reported owning `changedPath`: the path itself or an ancestor
+ * was reported. A collapsed `dir/` that only contains a reported entry stays
+ * unowned, since porcelain hides what else changed inside it.
  */
-const OPENSPEC_GENERATED = [
-  /^\.(claude|agents|opencode)\/skills\/openspec-[^/]+(\/|$)/,
-  /^\.agents\/skills\/\.openspec-target$/,
-  /^\.claude\/commands\/opsx(\/|$)/,
-  /^\.opencode\/commands\/opsx-[^/]+$/,
-];
-
-export function isOpenSpecGenerated(relativePath: string): boolean {
-  return OPENSPEC_GENERATED.some((pattern) => pattern.test(relativePath));
-}
-
-/** Mate-owned skills: `applyMateSkills` overwrites them wholesale, so a local edit there never survives a sync. */
-const MATE_MANAGED_SKILL = new RegExp(
-  `^\\.(claude|agents|opencode)/skills/(${MANAGED_MATE_SKILL_NAMES.join("|")})(/|$)`,
-);
-
-export function isMateManagedSkill(relativePath: string): boolean {
-  return MATE_MANAGED_SKILL.test(relativePath);
+export function ownerOf(
+  changedPath: string,
+  report: ManagedOutputReport,
+): ManagedOutputOwner | undefined {
+  const target = changedPath.replace(/\/+$/, "");
+  return report.find((entry) => target === entry.path || target.startsWith(`${entry.path}/`))
+    ?.owner;
 }
 
 function frameworkConfigPath(companionPath: string): string {
@@ -96,9 +91,18 @@ export interface CompanionUpdateDeps {
   getCurrentVersion: () => string;
   fetchLatestVersion: () => Promise<string>;
   loadConfig: (companionPath: string) => Promise<FrameworkConfig>;
-  syncCompanionFiles: (companionPath: string, config: FrameworkConfig) => Promise<void>;
+  syncCompanionFiles: (
+    companionPath: string,
+    config: FrameworkConfig,
+    options: CompanionSyncOptions,
+  ) => Promise<ManagedOutputReport>;
   /** Returns true when the file was rewritten. */
   writeEngineFloor: (companionPath: string, range: string) => Promise<boolean>;
+  /** Re-links the companion's Claude skills and commands into its wrapped Working Repositories. */
+  refreshWorkingClaudeLinks: (
+    companionPath: string,
+    config: FrameworkConfig,
+  ) => Promise<LinkRefreshResult[]>;
   hasSkillsLock: (companionPath: string) => Promise<boolean>;
   runSkillsUpdate: (companionPath: string) => Promise<void>;
   createGitOps: (companionPath: string) => GitOps;
@@ -114,7 +118,10 @@ export const companionUpdateDeps: CompanionUpdateDeps = {
   getCurrentVersion,
   fetchLatestVersion,
   loadConfig: (companionPath) => new ConfigStore(frameworkConfigPath(companionPath)).load(),
-  syncCompanionFiles,
+  /** The Claude plugin folders it gathers are for a launch; an update ignores them. */
+  async syncCompanionFiles(companionPath, config, options) {
+    return (await syncCompanionFiles(companionPath, config, undefined, options)).managedOutput;
+  },
   async writeEngineFloor(companionPath, range) {
     const store = new RawFrameworkConfigStore(frameworkConfigPath(companionPath));
     const raw = (await store.load()) ?? {};
@@ -123,6 +130,7 @@ export const companionUpdateDeps: CompanionUpdateDeps = {
     await store.save({ ...raw, engines: { ...engines, [FRAMEWORK_NAME]: range } });
     return true;
   },
+  refreshWorkingClaudeLinks,
   hasSkillsLock: (companionPath) =>
     fs
       .access(path.join(companionPath, SKILLS_LOCKFILE))
@@ -160,6 +168,7 @@ export async function diffChangedPaths(
   companionPath: string,
   git: GitOps,
   before: Map<string, string>,
+  report: ManagedOutputReport,
 ): Promise<UpdateChanges> {
   const written: string[] = [];
   const conflict: string[] = [];
@@ -168,19 +177,17 @@ export async function diffChangedPaths(
     if (!before.has(changed)) written.push(changed);
   }
   const preexisting = await Promise.all(
-    [...before].map(async ([changed, hash]) => ({
-      changed,
-      openspec: isOpenSpecGenerated(changed),
-      mate: isMateManagedSkill(changed),
-      unchanged: (await companionUpdateDeps.snapshotPath(companionPath, changed)) === hash,
-    })),
+    [...before].map(async ([changed, hash]) => {
+      const after = await companionUpdateDeps.snapshotPath(companionPath, changed);
+      return { changed, owner: ownerOf(changed, report), unchanged: after === hash };
+    }),
   );
-  for (const { changed, openspec, mate, unchanged } of preexisting) {
-    /** Generated output is committed even when a prior run already wrote identical content. */
-    if (!openspec && !mate && unchanged) continue;
+  for (const { changed, owner, unchanged } of preexisting) {
+    // Reported output is committed even when a local edit preceded the sync.
+    if (!owner && unchanged) continue;
     written.push(changed);
-    if (openspec || (mate && unchanged)) continue;
-    (mate ? overwritten : conflict).push(changed);
+    if (owner === "openspec" || (owner === "mate" && unchanged)) continue;
+    (owner === "mate" ? overwritten : conflict).push(changed);
   }
   return {
     written: written.toSorted(),
@@ -200,14 +207,27 @@ function fail(message: string): void {
   process.exitCode = 1;
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function listPaths(paths: string[]): string {
   return paths.map((changed) => `  ${changed}`).join("\n");
 }
 
+function reportLinkRefresh(results: LinkRefreshResult[]): void {
+  for (const result of results) {
+    const where = result.repository?.path ?? "the linked Working Repositories";
+    if (result.outcome === "written") {
+      process.stdout.write(
+        `${FRAMEWORK_NAME}: refreshed Claude skill and command links in ${where}.\n`,
+      );
+    } else if (result.outcome === "current") {
+      process.stdout.write(`${FRAMEWORK_NAME}: Claude links already current in ${where}.\n`);
+    } else {
+      process.stderr.write(
+        `${FRAMEWORK_NAME}: warning: could not refresh Claude links in ${where}: ${result.error}\n`,
+      );
+    }
+  }
+}
+
 /** Version precondition; returns the running version when the update may proceed. */
 async function checkVersion(): Promise<string | undefined> {
   const current = companionUpdateDeps.getCurrentVersion();
@@ -313,9 +333,14 @@ export async function runCompanionUpdateCommand(argv: string[]): Promise<void> {
     return;
   }
 
+  let config: FrameworkConfig;
+  let report: ManagedOutputReport;
   try {
-    const config = await companionUpdateDeps.loadConfig(companionPath);
-    await companionUpdateDeps.syncCompanionFiles(companionPath, config);
+    config = await companionUpdateDeps.loadConfig(companionPath);
+    // Only this command and setup regenerate OpenSpec output; launches leave it alone.
+    report = await companionUpdateDeps.syncCompanionFiles(companionPath, config, {
+      regenerateOpenSpec: true,
+    });
   } catch (error) {
     fail(`companion file synchronization failed: ${errorMessage(error)}`);
     return;
@@ -331,6 +356,9 @@ export async function runCompanionUpdateCommand(argv: string[]): Promise<void> {
     }
   }
 
+  // Working Repositories are outside the companion, so their links never join its commit.
+  reportLinkRefresh(await companionUpdateDeps.refreshWorkingClaudeLinks(companionPath, config));
+
   try {
     await companionUpdateDeps.writeEngineFloor(companionPath, `>=${version}`);
   } catch (error) {
@@ -338,7 +366,12 @@ export async function runCompanionUpdateCommand(argv: string[]): Promise<void> {
     return;
   }
 
-  const { written, conflict, overwritten } = await diffChangedPaths(companionPath, git, before);
+  const { written, conflict, overwritten } = await diffChangedPaths(
+    companionPath,
+    git,
+    before,
+    report,
+  );
   if (written.length === 0) {
     process.stdout.write(
       `${FRAMEWORK_NAME}: ${companionPath} is already up to date with ${FRAMEWORK_NAME} ${version}.\n`,