@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

package/src/cli/commands/workspace/materialize.ts

@@ -1,46 +0,0 @@
-import { materializeWorkspace } from "../../../lib/orchestrator/workspace-materialize";
-import { writeJsonStdout } from "../../write-json-stdout";
-
-export const workspaceMaterializeCommandDeps = {
-  materializeWorkspace: (repositoryId: string, companionPath: string) =>
-    materializeWorkspace({ repositoryId, companionPath }),
-};
-
-function readFlag(argv: string[], name: string): string | undefined {
-  const index = argv.indexOf(name);
-  return index >= 0 ? argv[index + 1] : undefined;
-}
-
-/**
- * @command mate workspace materialize
- * @description Validates an explicit repository/companion pairing, writes
- * the generated `.mate/workspace.code-workspace` file, and prints its path
- * and folder order as one JSON document. Never spawns or focuses an editor.
- * @flags
- * - `--repository <id>` — required; the linked repository id to pair.
- * - `--companion <path>` — required; the companion path that must link it.
- * - `--json` — required; this command only supports JSON output.
- */
-export async function runWorkspaceMaterializeCommand(argv: string[] = []): Promise<void> {
-  const repositoryId = readFlag(argv, "--repository");
-  const companionPath = readFlag(argv, "--companion");
-
-  if (!repositoryId || !companionPath || !argv.includes("--json")) {
-    process.stderr.write(
-      "mate: `workspace materialize` requires --repository <id>, --companion <path>, and --json.\n",
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  try {
-    const result = await workspaceMaterializeCommandDeps.materializeWorkspace(
-      repositoryId,
-      companionPath,
-    );
-    await writeJsonStdout(result);
-  } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    process.exitCode = 1;
-  }
-}

package/src/cli/commands/workspace/workspace.ts

@@ -1,22 +0,0 @@
-import { usage } from "../../usage";
-import { runWorkspaceListCommand } from "./list";
-import { runWorkspaceMaterializeCommand } from "./materialize";
-
-/** Dispatches `mate workspace <subcommand>`. Distinct from `mate companion open`. */
-export async function runWorkspaceCommand(
-  subcommand: string | undefined,
-  argv: string[],
-): Promise<void> {
-  switch (subcommand) {
-    case "list":
-      await runWorkspaceListCommand(argv);
-      return;
-    case "materialize":
-      await runWorkspaceMaterializeCommand(argv);
-      return;
-    default:
-      console.error(`Unknown workspace command: ${subcommand ?? ""}`);
-      console.error(usage());
-      process.exitCode = 1;
-  }
-}

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

@@ -1,244 +0,0 @@
-// 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;
-}
-
-// Best-effort shell variable substitution, NOT a shell interpreter: a change
-// name is often built up through variables (DEST="...archive/$TARGET"; mv a
-// "$DEST") rather than appearing as a literal path next to mv/archive. This
-// resolves $NAME/${NAME} references against preceding literal NAME=value
-// assignment tokens in the same command string; unresolved references are
-// left as-is, which keeps prior (silent) behavior for anything it can't follow.
-const ASSIGNMENT_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/;
-const VARIABLE_REFERENCE_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
-
-function substituteVariables(value: string, vars: Map<string, string>): string {
-  return value.replace(VARIABLE_REFERENCE_PATTERN, (match, braced: string, bare: string) => {
-    const name = braced ?? bare;
-    return vars.has(name) ? vars.get(name)! : match;
-  });
-}
-
-// Assignments are collected in left-to-right token order so a later
-// assignment (e.g. DEST) can reference an earlier one (e.g. TARGET) the same
-// way the shell would resolve it at that point in the script.
-function collectVariableAssignments(parts: string[]): Map<string, string> {
-  const vars = new Map<string, string>();
-  for (const part of parts) {
-    const match = part.match(ASSIGNMENT_PATTERN);
-    if (!match) continue;
-    const [, name, rawValue] = match;
-    vars.set(name, substituteVariables(rawValue, vars));
-  }
-  return vars;
-}
-
-// 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;
-  const vars = collectVariableAssignments(parts);
-  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 substituteVariables(part, vars);
-  }
-  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);
-  const vars = collectVariableAssignments(parts);
-  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(substituteVariables(part, vars));
-        if (change) return change;
-      }
-    }
-    if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
-      return extractChangeFromPath(substituteVariables(command, vars));
-    }
-  }
-  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/lib/orchestrator/headroom/proxy.ts

@@ -1,116 +0,0 @@
-import { spawn } from "node:child_process";
-import { closeSync, existsSync, openSync, readFileSync } from "node:fs";
-import http from "node:http";
-import os from "node:os";
-import path from "node:path";
-
-export interface SpawnProxyOpts {
-  port: number;
-}
-
-export interface WaitForProxyReachableOptions {
-  attempts?: number;
-  delayMs?: number;
-  probe?: (port: number) => Promise<boolean>;
-  sleep?: (ms: number) => Promise<void>;
-}
-
-export function resolveHeadroomPort(): number {
-  const portStr = process.env.HEADROOM_PORT;
-  if (portStr) {
-    const parsed = parseInt(portStr, 10);
-    if (!isNaN(parsed) && parsed > 0) return parsed;
-  }
-  return 8787;
-}
-
-export function isProxyReachable(port: number): Promise<boolean> {
-  const readyFile = process.env.MATE_E2E_HEADROOM_PROXY_READY_FILE;
-  if (readyFile && existsSync(readyFile)) {
-    return Promise.resolve(true);
-  }
-
-  return new Promise((resolve) => {
-    const req = http.get({ hostname: "127.0.0.1", port, path: "/livez", timeout: 2000 }, (res) => {
-      const statusCode = res.statusCode ?? 0;
-      resolve(statusCode >= 200 && statusCode < 300);
-      res.resume();
-    });
-    req.on("error", () => resolve(false));
-    req.on("timeout", () => {
-      req.destroy();
-      resolve(false);
-    });
-  });
-}
-
-export async function waitForProxyReachable(
-  port: number,
-  options: WaitForProxyReachableOptions = {},
-): Promise<boolean> {
-  const attempts = options.attempts ?? 20;
-  const delayMs = options.delayMs ?? 250;
-  const probe = options.probe ?? isProxyReachable;
-  const sleep =
-    options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
-
-  for (let attempt = 0; attempt < attempts; attempt += 1) {
-    if (await probe(port)) {
-      return true;
-    }
-
-    if (attempt < attempts - 1) {
-      await sleep(delayMs);
-    }
-  }
-
-  return false;
-}
-
-// Global map to store proxy stderr for error reporting. Keyed by port number.
-const proxyStderr = new Map<number, string>();
-const proxyStderrLogPath = new Map<number, string>();
-
-export function spawnProxyBackground(opts: SpawnProxyOpts, spawnFn: typeof spawn = spawn): void {
-  // Persistent memory is intentionally not enabled: headroom treats memory as
-  // opt-in (`--memory`), so a bare `proxy --port` runs compression-only with no
-  // memory DB writes.
-  const args = ["proxy", "--port", String(opts.port)];
-
-  let stderrBuffer = "";
-  const stderrLogPath = path.join(os.tmpdir(), `mate-headroom-proxy-${opts.port}.stderr.log`);
-  proxyStderrLogPath.set(opts.port, stderrLogPath);
-  const stderrFd = openSync(stderrLogPath, "w");
-  const child = spawnFn("headroom", args, {
-    detached: true,
-    stdio: ["ignore", "ignore", stderrFd],
-    env: { ...process.env, HEADROOM_OUTPUT_SHAPER: "0", HEADROOM_TELEMETRY: "off" },
-  });
-  closeSync(stderrFd);
-
-  // Tests may inject a mocked child.stderr; real detached launches use a log file.
-  if (child.stderr) {
-    child.stderr.on("data", (chunk) => {
-      stderrBuffer += chunk.toString();
-    });
-    child.stderr.on("end", () => {
-      proxyStderr.set(opts.port, stderrBuffer);
-    });
-  }
-
-  child.unref();
-}
-
-export function getProxyStderr(port: number): string {
-  const buffered = proxyStderr.get(port);
-  if (buffered) return buffered;
-
-  const logPath = proxyStderrLogPath.get(port);
-  if (!logPath || !existsSync(logPath)) return "";
-
-  try {
-    return readFileSync(logPath, "utf8");
-  } catch {
-    return "";
-  }
-}

package/src/lib/orchestrator/workspace-materialize.ts

@@ -1,80 +0,0 @@
-import path from "node:path";
-
-import { readCompanionRegistry } from "./companion-registry-reader";
-import { pathIsDirectory } from "./repo-local-registry";
-import { MateError } from "./types";
-import { writeWorkspaceDocument } from "./editor";
-
-/** Envelope version for `mate workspace materialize --json`. */
-export const MATERIALIZED_WORKSPACE_SCHEMA_VERSION = 1;
-
-export interface MaterializedWorkspaceV1 {
-  schemaVersion: 1;
-  workspacePath: string;
-  folders: [string, string];
-}
-
-export class WorkspacePairingNotFoundError extends MateError {
-  constructor(repositoryId: string, companionPath: string) {
-    super(`mate: repository "${repositoryId}" is not linked by companion: ${companionPath}`);
-  }
-}
-
-export class WorkspaceRootUnavailableError extends MateError {
-  constructor(
-    readonly root: "companion" | "repository",
-    readonly rootPath: string,
-  ) {
-    super(`mate: ${root} path does not exist: ${rootPath}`);
-  }
-}
-
-export interface MaterializeWorkspaceRequest {
-  repositoryId: string;
-  companionPath: string;
-}
-
-export interface MaterializeWorkspaceDeps {
-  isDirectory: (candidatePath: string) => Promise<boolean>;
-  readCompanionRegistry: typeof readCompanionRegistry;
-  writeWorkspaceDocument: typeof writeWorkspaceDocument;
-}
-
-export function defaultMaterializeWorkspaceDeps(): MaterializeWorkspaceDeps {
-  return { isDirectory: pathIsDirectory, readCompanionRegistry, writeWorkspaceDocument };
-}
-
-/**
- * Resolves an explicit companion-path/repository-id pairing, validates both
- * roots exist, and writes the shared workspace document — without touching
- * the registry or spawning an editor. Distinct from `injectEditorFolder`,
- * which additionally launches/reloads an editor CLI.
- */
-export async function materializeWorkspace(
-  request: MaterializeWorkspaceRequest,
-  deps: MaterializeWorkspaceDeps = defaultMaterializeWorkspaceDeps(),
-): Promise<MaterializedWorkspaceV1> {
-  const companionPath = path.resolve(request.companionPath);
-
-  if (!(await deps.isDirectory(companionPath))) {
-    throw new WorkspaceRootUnavailableError("companion", companionPath);
-  }
-
-  const { repos } = await deps.readCompanionRegistry(companionPath).catch(() => ({ repos: [] }));
-  const repository = repos.find((repo) => repo.id === request.repositoryId);
-  if (!repository) {
-    throw new WorkspacePairingNotFoundError(request.repositoryId, companionPath);
-  }
-
-  const repositoryPath = path.resolve(repository.path);
-  if (!(await deps.isDirectory(repositoryPath))) {
-    throw new WorkspaceRootUnavailableError("repository", repositoryPath);
-  }
-
-  const { workspacePath, folders } = await deps.writeWorkspaceDocument(
-    companionPath,
-    repositoryPath,
-  );
-
-  return { schemaVersion: MATERIALIZED_WORKSPACE_SCHEMA_VERSION, workspacePath, folders };
-}

package/src/templates/capabilities/openspec-cap/mate-skills/agents/mate-artifact-finish/SKILL.md

@@ -1,51 +0,0 @@
----
-name: mate-artifact-finish
-description: Finish a completed artifact in one step via `mate artifact finish`. Use when the user wants to finish, ship, or archive-and-push a completed artifact and anchor it with a dated revert tag.
-allowed-tools: Bash(mate:*), Bash(git:*), Bash(openspec:*)
-license: MIT
-compatibility: Requires the mate CLI and the openspec capability enabled.
-metadata:
-  author: mate
-  version: "1.2"
----
-
-Finish a completed artifact as one deterministic mate workflow and leave a dated tag that makes rollback trivial.
-
-## Workflow
-
-`mate artifact finish` is the deterministic, non-interactive finish pipeline.
-
-The CLI performs normal work; only conflict recovery requires agent judgment.
-
-## Steps
-
-1. **Resolve the artifact name.** Use the archived change named in the triggering context. If absent, use the single active OpenSpec change from `openspec list --json`. Ask only when multiple active changes remain ambiguous.
-
-2. **Run the CLI.**
-
-   ```bash
-   mate artifact finish "<artifact-name>" --json
-   ```
-
-   Run it from the companion repository. Finish mutates only that repository; the linked working repository is capability-indexing context. Do not manually invoke `mate cap index`.
-
-   Add `--force` only if the user explicitly wants to override the not-complete guard (validation is never bypassable). Unrelated companion changes are preserved and do not require `--force`. Add `--no-push` for a local-only finish.
-
-3. **Parse the JSON result and branch on `status`.**
-
-   For the exact field meanings and the provider-specific conflict path, read [references/openspec.md](references/openspec.md).
-
-   - **`ok`** → Report success and mention whether it resumed from an already-produced artifact.
-   - **`skipped`** → Report that the finish completed locally without pushing.
-   - **`error`** → Surface the failing step and message, then explain what local state exists.
-   - **`conflict`** → Follow the provider-specific conflict workflow in [references/openspec.md](references/openspec.md). Do not blindly rerun the finish command.
-
-## Guardrails
-
-- **CRITICAL — no manual finishing**: Never hand-commit or hand-tag instead of this skill. For a still-active change the finish pipeline applies delta specs itself (via `openspec archive`) — do not pre-apply them, or produce fails with "already exists". A change whose specs were already synced (e.g. via `openspec-sync-specs`) must be archived first; finish then resumes from the archive without re-applying delta specs.
-- Always pass `--json` and parse the result; do not scrape human-readable output.
-- Never re-run `mate artifact finish` blindly after a `conflict`.
-- Never auto-resolve a provider-specific conflict you do not understand — ask the user.
-- Use the JSON fields the CLI returns; do not recompute names, dates, or tags by hand.
-- Invoke the CLI as `mate`, never through a companion-local wrapper.
-- Only the companion repository is a finish Git target; the working repository is an index input.