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

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

@@ -12,12 +12,15 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { artifactRefusal, resolveArtifactTarget } from "../runtime/artifact-refusal";
+import { checkCommitAttribution } from "../runtime/commit-attribution-guard";
 import { gitEnvironment } from "../runtime/companion-git";
 import { companionForkRefusal } from "../runtime/companion-sync";
 import { readCompanionRuntimeContext } from "../runtime/env";
 import { companionLinkPath } from "../runtime/repo-local";
-
-export type HookEnv = Record<string, string | undefined>;
+import { checkSecretAccess, type SecretToolCall } from "../runtime/secret-guard";
+import { stripHeredocBodies } from "../runtime/shell-heredoc";
+import type { HookEnv } from "./hook-io";
 
 export interface HookOutcome {
   exitCode: number;
@@ -44,8 +47,9 @@ const ARTIFACT_PATH_MARKERS = [
   "/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;
+/** `[ \t]`, not `\s`: a redirect or `tee` names its target on its own line. */
+const MD_REDIRECT_PATTERN = />{1,2}[ \t]*([^\s;|&<>]+\.md)\b/g;
+const MD_TEE_PATTERN = /\btee[ \t]+(?:-a[ \t]+)?([^\s;|&<>]+\.md)\b/g;
 
 export function artifactLikePath(filePath: string): boolean {
   if (!filePath) return false;
@@ -118,11 +122,6 @@ function claudeConfigRoot(env: HookEnv): string {
   return path.normalize(path.join(env.HOME || os.homedir(), ".claude"));
 }
 
-function normalizePath(filePath: string, ctx: GuardContext): string {
-  if (path.isAbsolute(filePath)) return path.normalize(filePath);
-  return path.normalize(path.join(ctx.repoRoot, 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));
@@ -181,17 +180,14 @@ function isProductDocumentationPath(target: string, ctx: GuardContext): boolean
   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 blockWrite(target: string, resolved: string, ctx: GuardContext): HookOutcome {
+  const refusal = artifactRefusal({
+    target,
+    resolved,
+    companion: ctx.companion,
+    repoRoot: ctx.repoRoot,
+  });
+  return { exitCode: 2, stderr: `${refusal}\n` };
 }
 
 function checkFilePath(
@@ -201,7 +197,7 @@ function checkFilePath(
 ): HookOutcome | null {
   if (!filePath) return null;
 
-  const normalized = normalizePath(filePath, ctx);
+  const normalized = resolveArtifactTarget(filePath, ctx.repoRoot);
   if (isCompanionPath(normalized, ctx)) return null;
 
   if (isUnder(normalized, claudeConfigRoot(ctx.env))) return null;
@@ -219,7 +215,7 @@ function checkFilePath(
     return null;
   }
 
-  return blockWrite(filePath, ctx.companion);
+  return blockWrite(filePath, normalized, ctx);
 }
 
 /**
@@ -234,17 +230,19 @@ async function checkForkedCompanion(
   ctx: GuardContext,
 ): Promise<HookOutcome | null> {
   if (!filePath || !artifactLikePath(filePath)) return null;
-  if (!isCompanionPath(normalizePath(filePath, ctx), ctx)) return null;
+  if (!isCompanionPath(resolveArtifactTarget(filePath, ctx.repoRoot), ctx)) return null;
 
   const refusal = await companionForkRefusal(ctx.env, ctx.companion);
   return refusal ? { exitCode: 2, stderr: `${refusal}\n` } : null;
 }
 
+/** Heredoc bodies are what a command writes, not what it runs: they are not scanned. */
 export function commandMatches(command: string): string[] {
   const targets: string[] = [];
+  const commandText = stripHeredocBodies(command);
   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)) {
+    for (const match of commandText.matchAll(matcher)) {
       const target = match[1].trim().replace(/^["']+|["']+$/g, "");
       if (target) targets.push(target);
     }
@@ -252,6 +250,53 @@ export function commandMatches(command: string): string[] {
   return targets;
 }
 
+/** Claude tool payloads in the shape the shared secret guard reads. */
+function secretToolCall(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  ctx: GuardContext,
+): SecretToolCall | null {
+  const text = (value: unknown) => (typeof value === "string" ? value : "");
+  const target = (value: unknown) =>
+    text(value) ? resolveArtifactTarget(text(value), ctx.repoRoot) : "";
+  switch (toolName) {
+    case "Read":
+      return { kind: "read", paths: [target(toolInput.file_path)] };
+    case "Write":
+      return {
+        kind: "write",
+        writes: [{ path: target(toolInput.file_path), content: text(toolInput.content) }],
+      };
+    case "Edit":
+      return {
+        kind: "write",
+        writes: [{ path: target(toolInput.file_path), content: text(toolInput.new_string) }],
+      };
+    case "MultiEdit": {
+      const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
+      const content = edits
+        .map((edit) => (edit && typeof edit === "object" ? text(edit.new_string) : ""))
+        .join("\n");
+      return { kind: "write", writes: [{ path: target(toolInput.file_path), content }] };
+    }
+    case "NotebookEdit":
+      return {
+        kind: "write",
+        writes: [{ path: target(toolInput.notebook_path), content: text(toolInput.new_source) }],
+      };
+    case "Bash":
+      return { kind: "shell", command: text(toolInput.command) };
+    case "Grep":
+      return {
+        kind: "search",
+        paths: [target(toolInput.path)],
+        globs: [text(toolInput.glob)],
+      };
+    default:
+      return null;
+  }
+}
+
 /**
  * Fails open only when no Mate context resolves from either source; in a
  * wrapped Working Repository the guard runs without a launch.
@@ -273,6 +318,16 @@ export async function evaluate(
       ? (input.tool_input as Record<string, unknown>)
       : {};
 
+  /** Secrets first: a secret refusal wins over every artifact-placement verdict. */
+  const secretCall = secretToolCall(toolName, toolInput, ctx);
+  if (secretCall) {
+    const refusal = await checkSecretAccess(secretCall, {
+      companionPath: ctx.companion,
+      isCompanionPath: (target) => isCompanionPath(target, ctx),
+    });
+    if (refusal) return { exitCode: 2, stderr: `${refusal}\n` };
+  }
+
   if (toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
     const filePath = String(toolInput.file_path ?? "");
     /** The path refusal wins when both apply: its message is not replaced. */
@@ -282,6 +337,9 @@ export async function evaluate(
 
   if (toolName === "Bash") {
     const command = String(toolInput.command ?? "");
+    const attribution = checkCommitAttribution(command);
+    if (attribution) return { exitCode: 2, stderr: `${attribution}\n` };
+
     const targets = commandMatches(command);
     for (const target of targets) {
       const outcome = checkFilePath(target, ctx);

package/src/index.ts

@@ -39,13 +39,17 @@ export type {
   McpService,
   Plugin,
   PluginCliCommand,
+  PluginDirectoryContribution,
   PluginPolicy,
   PluginRegistration,
   ProviderHosting,
   ProviderPlugin,
+  RuntimeContributions,
+  RuntimeContributionsByRuntime,
   SetupContext,
   TemplatesService,
 } from "./tools/setup/plugin";
+export type { SessionKind } from "./runtime/session-kind";
 export type {
   FrameworkType,
   FrameworkConfig,

package/src/lib/change-layout.ts

@@ -0,0 +1,154 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { pathIsDirectory } from "./fs-utils";
+
+/**
+ * Where a change lives in a Companion Repository: the active `openspec/changes/<name>/`
+ * directory, its dated archive `openspec/changes/archive/YYYY-MM-DD-<name>/`, and the
+ * canonical specs its delta specs map to. Only directories count, and only names are read.
+ */
+
+/** Companion-relative POSIX paths. */
+export const CHANGES_RELATIVE_DIR = "openspec/changes";
+export const ARCHIVE_RELATIVE_DIR = "openspec/changes/archive";
+export const SPECS_RELATIVE_DIR = "openspec/specs";
+
+const ARCHIVE_DIR_NAME = "archive";
+
+/**
+ * One path segment: no separator, NUL, or leading dot (so never `.`, `..`, or hidden).
+ * Wider than OpenSpec's kebab-case, so archives made under older rules still resolve.
+ */
+const SEGMENT = /^[^./\\\0][^/\\\0]*$/;
+
+/** The `YYYY-MM-DD-<name>` anchor `openspec archive` gives an archived change. */
+const ANCHOR = /^(\d{4}-\d{2}-\d{2})-(.+)$/;
+
+export function changesDirOf(companionPath: string): string {
+  return path.join(companionPath, ...CHANGES_RELATIVE_DIR.split("/"));
+}
+
+export function archiveDirOf(companionPath: string): string {
+  return path.join(companionPath, ...ARCHIVE_RELATIVE_DIR.split("/"));
+}
+
+/** A change name or archive anchor: one path segment that is not the archive directory. */
+export function isChangeName(candidate: string): boolean {
+  return SEGMENT.test(candidate) && candidate !== ARCHIVE_DIR_NAME;
+}
+
+export interface Anchor {
+  date: string;
+  name: string;
+}
+
+/** `2026-01-02-acme` → `{date: "2026-01-02", name: "acme"}`; null for anything else, `2026-01-02-` included. */
+export function parseAnchor(candidate: string): Anchor | null {
+  const match = ANCHOR.exec(candidate);
+  if (!match || !isChangeName(match[2])) return null;
+  return { date: match[1], name: match[2] };
+}
+
+/** The change name of an archive anchor (`2026-01-02-acme` → `acme`); other names pass through. */
+export function changeNameOf(anchorOrName: string): string {
+  return parseAnchor(anchorOrName)?.name ?? anchorOrName;
+}
+
+async function directoryNames(dir: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}
+
+/** Active change names, sorted. */
+export async function activeChanges(companionPath: string): Promise<string[]> {
+  return (await directoryNames(changesDirOf(companionPath))).filter(isChangeName).toSorted();
+}
+
+/** Archive anchors, optionally only those of change `name`, sorted oldest first. */
+export async function archiveAnchors(companionPath: string, name?: string): Promise<string[]> {
+  return (await directoryNames(archiveDirOf(companionPath)))
+    .filter((anchor) => {
+      const parsed = parseAnchor(anchor);
+      return parsed !== null && (name === undefined || parsed.name === name);
+    })
+    .toSorted();
+}
+
+export interface ChangeLocation {
+  dir: string;
+  archived: boolean;
+}
+
+/**
+ * Resolves a change name or anchor to its directory: the archive an anchor names exactly,
+ * else the active change, else the newest archive of that name. Anything that is not a
+ * single change-name segment resolves to nothing.
+ */
+export async function locateChange(
+  companionPath: string,
+  target: string,
+): Promise<ChangeLocation | null> {
+  if (!isChangeName(target)) return null;
+  const archiveDir = archiveDirOf(companionPath);
+  if (parseAnchor(target) && (await pathIsDirectory(path.join(archiveDir, target)))) {
+    return { dir: path.join(archiveDir, target), archived: true };
+  }
+  const active = path.join(changesDirOf(companionPath), target);
+  if (await pathIsDirectory(active)) return { dir: active, archived: false };
+  const newest = (await archiveAnchors(companionPath, target)).at(-1);
+  return newest ? { dir: path.join(archiveDir, newest), archived: true } : null;
+}
+
+export interface DeltaSpec {
+  /** POSIX path under the change's `specs/`, e.g. `identity/user-auth/spec.md`. */
+  file: string;
+  /** The companion-relative canonical path the file maps to. */
+  canonical: string;
+  /** The capability path of a `spec.md` below `specs/`; null for any other file. */
+  capability: string | null;
+}
+
+/**
+ * Every file below `dir` at any depth, as sorted POSIX paths relative to it. Reads directory
+ * entry names only, never contents; an unreadable directory contributes nothing.
+ */
+export async function filesBelow(dir: string): Promise<string[]> {
+  const walk = async (current: string, relative: string): Promise<string[]> => {
+    let entries;
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    const nested = await Promise.all(
+      entries.map(async (entry) => {
+        const entryRelative = relative ? `${relative}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) return walk(path.join(current, entry.name), entryRelative);
+        return entry.isFile() ? [entryRelative] : [];
+      }),
+    );
+    return nested.flat();
+  };
+  return (await walk(dir, "")).toSorted();
+}
+
+/**
+ * Every file under the change's `specs/`, at any depth, sorted. Reads directory entry
+ * names only, never contents. A change without `specs/` has none.
+ */
+export async function deltaSpecs(changeDir: string): Promise<DeltaSpec[]> {
+  const files = await filesBelow(path.join(changeDir, "specs"));
+  return files.map((file) => {
+    const capability = path.posix.dirname(file);
+    return {
+      file,
+      canonical: `${SPECS_RELATIVE_DIR}/${file}`,
+      capability: path.posix.basename(file) === "spec.md" && capability !== "." ? capability : null,
+    };
+  });
+}

package/src/lib/components/wizard-header.tsx

@@ -1,5 +1,7 @@
 import { Box, Text } from "ink";
 
+import { BRAND_ACCENT } from "../../brand/palette";
+
 interface WizardHeaderProps {
   title: string;
   step: number;
@@ -12,7 +14,7 @@ export function WizardHeader({ title, step, totalSteps }: WizardHeaderProps) {
   return (
     <Box borderStyle="round" width="100%">
       <Box flexDirection="column" flexGrow={1} marginLeft={1}>
-        <Text bold color="green">
+        <Text bold color={BRAND_ACCENT}>
           mate framework
         </Text>
         <Box justifyContent="space-between">

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

@@ -54,9 +54,17 @@ function validateContextModeNodeRuntime(): void {
 export async function validateContextModePackage(companionPath: string): Promise<void> {
   validateContextModeNodeRuntime();
   const root = getContextModePackageRoot(companionPath);
-  const manifest = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8")) as {
-    version?: string;
-  };
+  let manifestText: string;
+  try {
+    manifestText = await fs.readFile(path.join(root, "package.json"), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    throw new Error(
+      `Expected ${getContextModePackageReference()} at ${root}; it is not installed. Re-run \`mate companion setup\`.`,
+      { cause: error },
+    );
+  }
+  const manifest = JSON.parse(manifestText) as { version?: string };
   if (manifest.version !== CONTEXT_MODE_VERSION) {
     throw new Error(
       `Expected ${getContextModePackageReference()} at ${root}; found ${manifest.version ?? "an unknown version"}. Re-run \`mate companion setup\`.`,
@@ -72,6 +80,15 @@ export async function validateContextModePackage(companionPath: string): Promise
   );
 }
 
+export const contextModePackageDeps = {
+  runInstall: (cwd: string) =>
+    spawnSync(
+      "npm",
+      ["install", "--no-audit", "--no-fund", "--loglevel=error", "--registry", PUBLIC_NPM_REGISTRY],
+      { cwd, encoding: "utf8" as const, env: process.env },
+    ),
+};
+
 export async function installContextModePackage(companionPath: string): Promise<void> {
   validateContextModeNodeRuntime();
   const installDir = getContextModeInstallDir(companionPath);
@@ -85,15 +102,11 @@ export async function installContextModePackage(companionPath: string): Promise<
     ) + "\n",
     "utf8",
   );
-  const result = spawnSync(
-    "npm",
-    ["install", "--no-audit", "--no-fund", "--silent", "--registry", PUBLIC_NPM_REGISTRY],
-    { cwd: installDir, encoding: "utf8", env: process.env },
-  );
+  const result = contextModePackageDeps.runInstall(installDir);
   if (result.error || result.status !== 0) {
-    throw new Error(
-      `Could not install ${getContextModePackageReference()}: ${result.error?.message ?? result.stderr?.trim() ?? `npm exited with ${result.status}`}`,
-    );
+    const cause =
+      result.error?.message ?? (result.stderr?.trim() || `npm exited with ${result.status}`);
+    throw new Error(`Could not install ${getContextModePackageReference()}: ${cause}`);
   }
   await validateContextModePackage(companionPath);
 }

package/src/lib/delivery/archive-change.ts

@@ -0,0 +1,154 @@
+import { locateChange } from "../change-layout";
+import { runOpenSpec, type RunOpenSpec } from "../openspec-cli";
+import { companionRelative, type DeliveryEnvironment } from "./environment";
+import { archiveWarnings, planningWarning, type ArchiveWarning } from "./overlap";
+import {
+  isPublishable,
+  settleDelivery,
+  type DeliveryRecord,
+  type DeliverySettlement,
+  type UnscopedDelivery,
+} from "./record";
+import {
+  recordDelivery,
+  type DeliveryEdit,
+  type DeliveryRefusal,
+  type RecordDeliveryDeps,
+} from "./record-delivery";
+import type { BranchOutcome } from "./refresh";
+
+export type ArchiveStatus = "archived" | "needs-branch" | "failed";
+
+export interface ArchiveResult {
+  status: ArchiveStatus;
+  change: string;
+  /** Companion-relative archive directory, once archived. */
+  path: string | null;
+  record: DeliveryRecord;
+  settlement: DeliverySettlement;
+  outcomes: BranchOutcome[];
+  warnings: ArchiveWarning[];
+  /** `needs-branch` only: the branch to suggest, when it exists. */
+  suggestedBranch?: string | null;
+  message: string;
+}
+
+export interface ArchiveRequest {
+  change: string;
+  /** The repository `delivery` is recorded for; defaults to the Working Repository. */
+  repository?: string;
+  /** Recorded before the refresh, as `artifact link` would. */
+  delivery?: DeliveryEdit["delivery"];
+  /** Archive with an unlinked record instead of answering `needs-branch`. */
+  skipBranch?: boolean;
+}
+
+export type ArchiveOutcome = { refusal: DeliveryRefusal } | { result: ArchiveResult };
+
+export interface ArchiveChangeDeps extends RecordDeliveryDeps {
+  runOpenSpec?: RunOpenSpec;
+  /**
+   * Called once before `openspec archive` starts, so warnings are visible even when the
+   * archive fails or hangs. Never called for `needs-branch` or a refusal.
+   */
+  onWarnings?: (warnings: ArchiveWarning[], unscoped: UnscopedDelivery[]) => void;
+}
+
+/**
+ * The Archive change stage: records and refreshes the delivery, collects overlap,
+ * dependency, and incomplete-planning warnings, then runs `openspec archive`. Without a
+ * recorded delivery and no `skipBranch`, nothing is archived and the result is
+ * `needs-branch`. Merge state is reported, never a refusal.
+ */
+export async function archiveChange(
+  environment: DeliveryEnvironment,
+  request: ArchiveRequest,
+  deps: ArchiveChangeDeps = {},
+): Promise<ArchiveOutcome> {
+  const { change } = request;
+  const outcome = await recordDelivery(
+    environment,
+    {
+      changes: [change],
+      ...(request.repository ? { repository: request.repository } : {}),
+      ...(request.delivery ? { edit: { delivery: request.delivery } } : {}),
+      refresh: true,
+      // The settlement covers every repository, so each delivery's merge state is refreshed.
+      refreshAll: true,
+      requireDelivery: !request.skipBranch,
+    },
+    deps,
+  );
+  if ("refusal" in outcome) return outcome;
+
+  const runner = deps.runOpenSpec ?? runOpenSpec;
+  const cwd = environment.companionPath;
+  const [overlap, status] = await Promise.all([
+    archiveWarnings(environment.companionPath, change),
+    runner(["status", "--change", change, "--json"], { cwd }),
+  ]);
+  const planning = status.code === 0 ? planningWarning(change, status.stdout) : null;
+  const warnings = [...overlap, ...(planning ? [planning] : [])];
+
+  if ("needsBranch" in outcome) {
+    const { record, suggestedBranch } = outcome.needsBranch;
+    return {
+      result: {
+        status: "needs-branch",
+        change,
+        path: null,
+        record,
+        settlement: settleDelivery(record),
+        outcomes: [],
+        warnings,
+        suggestedBranch,
+        message: `No delivery branch is recorded for ${change}. Re-run with --branch <branch>, --not-applicable <reason>, or --skip-branch.`,
+      },
+    };
+  }
+
+  const [{ record, settlement, outcomes }] = outcome.results;
+  deps.onWarnings?.(warnings, settlement.unscoped);
+
+  const run = await runner(["archive", change, "--yes"], { cwd });
+  if (run.code !== 0) {
+    const detail = (run.stderr.trim() || run.stdout.trim()).split("\n").slice(-5).join("\n");
+    return {
+      result: {
+        status: "failed",
+        change,
+        path: null,
+        record,
+        settlement,
+        outcomes,
+        warnings,
+        message: `openspec archive ${change} failed (exit ${run.code ?? "unknown"}): ${detail}`,
+      },
+    };
+  }
+
+  const archived = await locateChange(environment.companionPath, change);
+  return {
+    result: {
+      status: "archived",
+      change,
+      path: archived?.archived ? companionRelative(environment, archived.dir) : null,
+      record,
+      settlement,
+      outcomes,
+      warnings,
+      message: archivedMessage(change, settlement),
+    },
+  };
+}
+
+function archivedMessage(change: string, settlement: DeliverySettlement): string {
+  if (isPublishable(settlement.status)) {
+    return `Archived ${change}; it can be published with mate-publish-artifact.`;
+  }
+  const missing =
+    settlement.missing.length > 0
+      ? ` No delivery is recorded for ${settlement.missing.join(", ")}, which its scopes name.`
+      : "";
+  return `Archived ${change}; publication waits until its delivery is merged (${settlement.status}).${missing}`;
+}