@uniqbit/mate-core 0.15.3 → 0.15.4-canary.10

package/src/distribution.ts

@@ -1,7 +1,7 @@
 import type { PluginRegistry } from "./tools/setup/registry";
 
 export interface DistributionUpdateConfig {
-  /** npm package whose versions are checked and installed by `mate update`. Defaults to `@uniqbit/<name>`. */
+  /** npm package whose versions are checked and installed by `mate update`. Defaults to `@uniqbit/mate`. */
   packageName?: string;
   /** npm registry used for update checks and downloads. Defaults to public npm. */
   registry?: string;
@@ -14,15 +14,13 @@ export interface DistributionUpdateConfig {
   enforce?: boolean;
 }
 
-/** Identity and version of the distribution assembled through `createMate`. */
+/** Version and plugin registry of the distribution assembled through `createMate`. */
 export interface DistributionConfig {
-  name: string;
-  legacyNames?: string[];
   runtime: "bun";
   version: string;
   /** Asset directories that override the framework defaults, highest precedence first. */
   assetRoots?: string[];
-  /** Optional update source; defaults to `@uniqbit/<name>` on public npm. */
+  /** Optional update source; defaults to `@uniqbit/mate` on public npm. */
   update?: DistributionUpdateConfig;
 }
 

package/src/framework.ts

@@ -1,39 +1,7 @@
-import { getActiveDistribution } from "./distribution";
-
 /**
- * Framework identity: names everything identity-shaped regardless of how the
- * CLI is invoked — state directories (`~/.mate`, `.mate/`), managed-block
- * markers, `MATE_*` env values, and the `companion-policy framework`
- * attribute. A whitelabel distribution changes the invocation name only;
- * identity stays `mate`. Use `frameworkCommandName()` for anything the user
- * or an agent types.
+ * Framework identity: names everything identity-shaped — state directories
+ * (`~/.mate`, `.mate/`), managed-block markers, `MATE_*` env values, usage
+ * output, command hints, error prefixes, agent guidance, and permission
+ * entries. The distribution is always invoked as `mate`.
  */
 export const FRAMEWORK_NAME = "mate";
-
-/**
- * Invocation name: how this distribution's CLI is invoked, derived from the
- * package's `bin` key (`config.name`). Drives usage output, command hints,
- * error prefixes, agent guidance, and permission entries — never paths,
- * markers, or env values (use `FRAMEWORK_NAME` for those).
- */
-export function frameworkCommandName(): string {
-  return getActiveDistribution().config.name;
-}
-
-/**
- * Live view of the active distribution's identity. Framework modules read
- * identity through this object; the values always come from the config the
- * distribution passed to `createMate` — the framework itself carries no
- * hardcoded distribution name.
- */
-export const frameworkConfig = {
-  get name(): string {
-    return getActiveDistribution().config.name;
-  },
-  get legacyNames(): string[] {
-    return getActiveDistribution().config.legacyNames ?? [];
-  },
-  get runtime(): string {
-    return getActiveDistribution().config.runtime;
-  },
-};

package/src/hooks/artifact-finish-nudge.ts

@@ -0,0 +1,212 @@
+// Nudge the agent into the mate-artifact-finish workflow after a Bash command
+// visibly archived an OpenSpec change. Stateless PostToolUse hook: never denies
+// or blocks; emits additionalContext only on apparent success.
+import type { HookEnv } from "./validate-artifact-path";
+
+export interface NudgeOutcome {
+  exitCode: number;
+  stdout: string;
+}
+
+const ARCHIVE_PATH_PATTERN =
+  /(?:^|[\s/"'`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^/\s"'`,)]+)/;
+
+// The nudge only applies when the openspec capability is enabled and OpenSpec
+// git auto mode is on; the plugin registers the hook unconditionally, so the
+// gate is evaluated here from launch-injected environment before any parsing.
+export function isGateEnabled(env: HookEnv): boolean {
+  return env.MATE_OPENSPEC_ENABLED === "1" && env.MATE_GIT_AUTO_MODE === "1";
+}
+
+export function shellSplit(command: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let quote: string | null = null;
+  let escaping = false;
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      const next = command[index + 1] || "";
+      if (next === "\\" || /\s/.test(next) || next === "'" || next === '"') {
+        escaping = true;
+        continue;
+      }
+    }
+    if ((char === "'" || char === '"') && !quote) {
+      quote = char;
+      continue;
+    }
+    if (quote === char) {
+      quote = null;
+      continue;
+    }
+    const next = command[index + 1] || "";
+    const previous = command[index - 1] || "";
+    const isControlOperator =
+      !quote &&
+      (char === ";" ||
+        char === "|" ||
+        (char === "&" && next !== ">" && previous !== ">" && previous !== "<"));
+    if (isControlOperator) {
+      if (current) parts.push(current);
+      current = "";
+      if ((char === "|" || char === "&") && next === char) {
+        parts.push(char + next);
+        index += 1;
+      } else {
+        parts.push(char);
+      }
+      continue;
+    }
+    if (!quote && /\s/.test(char)) {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+function extractChangeFromPath(value: string): string | null {
+  const match = value.replaceAll("\\", "/").match(ARCHIVE_PATH_PATTERN);
+  return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
+}
+
+// Shell syntax tokens are never change-name positionals: separators end the
+// archive invocation, redirections are skipped (a bare operator also consumes
+// its target token).
+const SEPARATOR_PATTERN = /^(\|\|?|&&?|;)$/;
+const REDIRECTION_PATTERN = /^(\d*(>>?|<)|&>>?)/;
+const BARE_REDIRECTION_PATTERN = /^(\d*(>>?|<)|&>>?)$/;
+
+export function extractArchiveCommand(command: string): string | null {
+  const parts = shellSplit(command);
+  const index = parts.findIndex(
+    (part, position) =>
+      part === "archive" &&
+      position > 0 &&
+      (parts[position - 1] === "openspec" || parts[position - 1].endsWith("/openspec")),
+  );
+  if (index < 0) return null;
+  for (let position = index + 1; position < parts.length; position += 1) {
+    const part = parts[position];
+    if (!part || part === "--") continue;
+    if (SEPARATOR_PATTERN.test(part)) return null;
+    if (REDIRECTION_PATTERN.test(part)) {
+      if (BARE_REDIRECTION_PATTERN.test(part)) position += 1;
+      continue;
+    }
+    if (part.startsWith("-")) {
+      if (part === "--store") position += 1;
+      continue;
+    }
+    return part;
+  }
+  return null;
+}
+
+const MOVE_COMMANDS = new Set([
+  "mv",
+  "move",
+  "move-item",
+  "cmd",
+  "cmd.exe",
+  "powershell",
+  "powershell.exe",
+  "pwsh",
+  "pwsh.exe",
+]);
+
+function isPython(part: string): boolean {
+  return /^python(?:\d(?:\.\d+)*)?(?:\.exe)?$/i.test(part.split(/[\\/]/).pop() || part);
+}
+
+export function extractMoveCommand(command: string): string | null {
+  const parts = shellSplit(command);
+  for (let index = 0; index < parts.length; index += 1) {
+    if (MOVE_COMMANDS.has(parts[index].toLowerCase())) {
+      for (const part of parts.slice(index + 1)) {
+        const change = extractChangeFromPath(part);
+        if (change) return change;
+      }
+    }
+    if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
+      return extractChangeFromPath(command);
+    }
+  }
+  return null;
+}
+
+// Nudge only on apparent success: stay silent on a clear failure indication,
+// nudge when success is indicated or indeterminate.
+export function isClearFailure(response: unknown): boolean {
+  if (!response || typeof response !== "object") return false;
+  const value = response as Record<string, unknown>;
+  if (value.success === false || value.is_error === true) return true;
+  if (typeof value.error === "string" && value.error) return true;
+  if (value.interrupted === true) return true;
+  const exitCode = value.exit_code ?? value.exitCode;
+  return typeof exitCode === "number" && exitCode !== 0;
+}
+
+export function evaluate(payload: unknown, env: HookEnv): NudgeOutcome {
+  const silent: NudgeOutcome = { exitCode: 0, stdout: "" };
+  if (!isGateEnabled(env)) return silent;
+
+  const input = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {};
+  if (input.hook_event_name !== "PostToolUse" || input.tool_name !== "Bash") return silent;
+
+  const toolInput =
+    input.tool_input && typeof input.tool_input === "object"
+      ? (input.tool_input as Record<string, unknown>)
+      : {};
+  const command = typeof toolInput.command === "string" ? toolInput.command : "";
+  const change = extractArchiveCommand(command) || extractMoveCommand(command);
+  if (!change) return silent;
+  if (isClearFailure(input.tool_response)) return silent;
+
+  const context =
+    `OpenSpec change ${change} was just archived. Invoke the mate-artifact-finish ` +
+    `skill, then run \`mate artifact finish "${change}" --json\` to complete the ` +
+    "finish workflow (commit, tag, and push).";
+  return {
+    exitCode: 0,
+    stdout: JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: context,
+      },
+    }),
+  };
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Plugin-shim entry. The gate check precedes stdin parsing so a disabled gate
+// costs one env read.
+export async function run(): Promise<number> {
+  if (!isGateEnabled(process.env)) return 0;
+
+  let payload: unknown = {};
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = {};
+  }
+  const outcome = evaluate(payload, process.env);
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  return outcome.exitCode;
+}

package/src/hooks/session-banner.ts

@@ -0,0 +1,25 @@
+// Show the active Mate companion paths in Claude Code.
+import type { HookEnv } from "./validate-artifact-path";
+
+export interface BannerOutcome {
+  exitCode: number;
+  stdout: string;
+}
+
+// Fail-soft outside managed sessions: no MATE_* env, no banner.
+export function buildBanner(env: HookEnv): BannerOutcome {
+  const repoPath = env.MATE_REPO_PATH;
+  const artifactPath = env.MATE_ARTIFACT_PATH;
+  if (!repoPath || !artifactPath) return { exitCode: 0, stdout: "" };
+
+  const mateVersion = env.MATE_VERSION || "unknown";
+  const message = `mate v${mateVersion}\n  repo:     ${repoPath}\n  mate: ${artifactPath}`;
+  return { exitCode: 0, stdout: JSON.stringify({ systemMessage: message }) + "\n" };
+}
+
+// Plugin-shim entry.
+export function run(): number {
+  const outcome = buildBanner(process.env);
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  return outcome.exitCode;
+}

package/src/hooks/validate-artifact-path.ts

@@ -0,0 +1,236 @@
+// Block artifact writes outside the companion framework path.
+//
+// Artifact-like files may be written in the working repository only when the
+// target path is already ignored by git. That keeps local-only scratch files
+// possible without weakening the default repo split.
+//
+// Editing a file that already exists is always allowed: the guard exists to
+// stop new agent artifacts from landing in the working repo, not to freeze
+// files that are already part of it.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type HookEnv = Record<string, string | undefined>;
+
+export interface HookOutcome {
+  exitCode: number;
+  stderr: string;
+}
+
+const KNOWN_ARTIFACT_BASENAMES = new Set([
+  "CLAUDE.md",
+  "CONTEXT.md",
+  "design.md",
+  "explore-brief.md",
+  "proposal.md",
+  "spec.md",
+  "tasks.md",
+]);
+
+const ARTIFACT_PATH_MARKERS = [
+  "/changes/",
+  "/openspec/",
+  "/specs/",
+  "/docs/adr/",
+  "/docs/adrs/",
+  "/docs/decisions/",
+  "/docs/prd/",
+];
+
+const MD_REDIRECT_PATTERN = />{1,2}\s*([^\s;|&<>]+\.md)\b/g;
+const MD_TEE_PATTERN = /\btee\s+(?:-a\s+)?([^\s;|&<>]+\.md)\b/g;
+
+export function artifactLikePath(filePath: string): boolean {
+  if (!filePath) return false;
+
+  const basename = path.basename(filePath);
+  const normalized = "/" + filePath.replaceAll("\\", "/").replace(/^\/+/, "");
+  if (KNOWN_ARTIFACT_BASENAMES.has(basename)) return true;
+
+  if (ARTIFACT_PATH_MARKERS.some((marker) => normalized.includes(marker))) return true;
+
+  if (basename.endsWith(".md") && basename !== "README.md") return true;
+
+  return false;
+}
+
+function repoRoot(env: HookEnv): string {
+  return env.MATE_REPO_PATH || process.cwd();
+}
+
+function companionRoot(env: HookEnv): string | null {
+  const companion = env.MATE_ARTIFACT_PATH;
+  return companion ? path.normalize(companion) : null;
+}
+
+// Claude Code's own config/state directory (plan files, settings, todos).
+// Writes there are agent-runtime state, never Mate artifacts.
+function claudeConfigRoot(env: HookEnv): string {
+  const configured = env.CLAUDE_CONFIG_DIR;
+  if (configured) return path.normalize(configured);
+  return path.normalize(path.join(env.HOME || os.homedir(), ".claude"));
+}
+
+function normalizePath(filePath: string, env: HookEnv): string {
+  if (path.isAbsolute(filePath)) return path.normalize(filePath);
+  return path.normalize(path.join(repoRoot(env), filePath));
+}
+
+function isUnder(target: string, root: string): boolean {
+  const relative = path.relative(path.normalize(root), path.normalize(target));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function isGitignored(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const result = spawnSync("git", ["-C", root, "check-ignore", "--no-index", "-q", "--", relPath], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+// A file already tracked in the working repo is product code being edited,
+// not a new agent artifact (e.g. packaged SKILL.md/spec.md template sources).
+function isGitTracked(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const result = spawnSync("git", ["-C", root, "ls-files", "--error-unmatch", "--", relPath], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+function isProductDocumentationPath(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const parts = relPath.split(path.sep).filter(Boolean);
+  for (const [index, part] of parts.entries()) {
+    if (part === ".storybook" || part === "storybook") return true;
+
+    if (part !== "docs") continue;
+
+    const docsRoot = path.join(root, ...parts.slice(0, index + 1));
+    if (fs.existsSync(path.join(docsRoot, "package.json"))) return true;
+  }
+
+  return false;
+}
+
+function blockWrite(target: string, companion: string): HookOutcome {
+  const lines = [
+    "Mate guardrail: artifact writes must go to the companion framework path.",
+    ` target: ${target}`,
+    ` companion: ${companion}`,
+    "Use an absolute path under MATE_ARTIFACT_PATH instead.",
+  ];
+  if (path.basename(target) === "CLAUDE.md") {
+    lines.push(`Note: CLAUDE.md already lives in the companion repo at ${companion}/CLAUDE.md.`);
+  }
+  return { exitCode: 2, stderr: lines.join("\n") + "\n" };
+}
+
+function checkFilePath(
+  filePath: string,
+  companion: string | null,
+  env: HookEnv,
+  allowExisting = false,
+): HookOutcome | null {
+  if (!filePath || !companion) return null;
+
+  const normalized = normalizePath(filePath, env);
+  if (normalized.startsWith(companion)) return null;
+
+  if (isUnder(normalized, claudeConfigRoot(env))) return null;
+
+  if (allowExisting && fs.existsSync(normalized) && fs.statSync(normalized).isFile()) return null;
+
+  if (isProductDocumentationPath(normalized, env)) return null;
+
+  if (!artifactLikePath(filePath)) return null;
+
+  if (
+    isUnder(normalized, repoRoot(env)) &&
+    (isGitignored(normalized, env) || isGitTracked(normalized, env))
+  ) {
+    return null;
+  }
+
+  return blockWrite(filePath, companion);
+}
+
+export function commandMatches(command: string): string[] {
+  const targets: string[] = [];
+  for (const pattern of [MD_REDIRECT_PATTERN, MD_TEE_PATTERN]) {
+    const matcher = new RegExp(pattern.source, pattern.flags);
+    for (const match of command.matchAll(matcher)) {
+      const target = match[1].trim().replace(/^["']+|["']+$/g, "");
+      if (target) targets.push(target);
+    }
+  }
+  return targets;
+}
+
+export function evaluate(payload: unknown, env: HookEnv): HookOutcome {
+  const allow: HookOutcome = { exitCode: 0, stderr: "" };
+
+  const companion = companionRoot(env);
+  if (!companion) return allow;
+
+  const input = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {};
+  const toolName = typeof input.tool_name === "string" ? input.tool_name : "";
+  const toolInput =
+    input.tool_input && typeof input.tool_input === "object"
+      ? (input.tool_input as Record<string, unknown>)
+      : {};
+
+  if (toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
+    const outcome = checkFilePath(
+      String(toolInput.file_path ?? ""),
+      companion,
+      env,
+      toolName === "Edit" || toolName === "MultiEdit",
+    );
+    return outcome ?? allow;
+  }
+
+  if (toolName === "Bash") {
+    const command = String(toolInput.command ?? "");
+    for (const target of commandMatches(command)) {
+      const outcome = checkFilePath(target, companion, env);
+      if (outcome) return outcome;
+    }
+    return allow;
+  }
+
+  return allow;
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Plugin-shim entry: read the hook payload from stdin, evaluate, report.
+export async function run(): Promise<number> {
+  let payload: unknown = {};
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = {};
+  }
+  const outcome = evaluate(payload, process.env);
+  if (outcome.stderr) process.stderr.write(outcome.stderr);
+  return outcome.exitCode;
+}

package/src/index.ts

@@ -47,7 +47,11 @@ export type {
   TemplatesService,
 } from "./tools/setup/plugin";
 export type {
+  FrameworkType,
   FrameworkConfig,
+  HubConfig,
+  HubMember,
+  HubMemberSource,
   PluginDeclaration,
   PluginDeclarationPolicy,
 } from "./lib/orchestrator/types";

package/src/lib/context-mode-package.ts

@@ -20,7 +20,7 @@ export function isContextModePackageReference(value: unknown): value is string {
 }
 
 export function getContextModeInstallDir(companionPath: string): string {
-  return path.join(companionPath, ".mate", "dependencies", CONTEXT_MODE_PACKAGE_NAME);
+  return path.join(companionPath, ".mate", "plugins", ".local");
 }
 
 export function getContextModePackageRoot(companionPath: string): string {
@@ -37,7 +37,9 @@ export function isContextModeNodeVersionSupported(version: string): boolean {
 }
 
 export function validateContextModeNodeRuntime(): void {
-  const result = spawnSync("node", ["--version"], { encoding: "utf8" });
+  // env passed explicitly: bun's spawnSync otherwise ignores in-process PATH
+  // changes when resolving the executable.
+  const result = spawnSync("node", ["--version"], { encoding: "utf8", env: process.env });
   const version = result.stdout?.trim() ?? "";
   if (result.status !== 0 || !isContextModeNodeVersionSupported(version)) {
     throw new Error(
@@ -83,7 +85,7 @@ export async function installContextModePackage(companionPath: string): Promise<
   const result = spawnSync(
     "npm",
     ["install", "--no-audit", "--no-fund", "--silent", "--registry", PUBLIC_NPM_REGISTRY],
-    { cwd: installDir, encoding: "utf8" },
+    { cwd: installDir, encoding: "utf8", env: process.env },
   );
   if (result.error || result.status !== 0) {
     throw new Error(