@xpufx/paseo-slash 0.1.0

package/server/vendor/paseo-plugin-helper/workspace-beacon.ts

@@ -0,0 +1,418 @@
+import type { PluginLogger } from "./logger";
+
+export const DEFAULT_BEACON_LABEL_PREFIX = "beacon:";
+
+export const BEACON_COLORS = [
+  "violet",
+  "sky",
+  "emerald",
+  "orange",
+  "pink",
+  "indigo",
+  "teal",
+  "red",
+  "amber",
+  "blue",
+] as const;
+
+export type BeaconColor = (typeof BEACON_COLORS)[number];
+
+export interface BeaconLabelState {
+  name: string;
+  color?: string;
+  titleSuffix?: string;
+  title?: string;
+  workspaceId?: string;
+}
+
+export interface BeaconSetOptions extends BeaconLabelState {
+  workspaceId: string;
+}
+
+export interface BeaconBlinkOptions {
+  workspaceId?: string;
+  a: BeaconLabelState;
+  b: BeaconLabelState;
+  intervalMs?: number;
+  rounds?: number;
+  restoreOnDone?: boolean;
+}
+
+export interface BeaconClearOptions {
+  workspaceId?: string;
+  name?: string;
+  restoreTitle?: boolean;
+}
+
+export interface WorkspaceTitleHandle {
+  setTitle?: (title: string) => unknown;
+}
+
+export interface BeaconDaemonClient {
+  setWorkspaceLabel?: (args: unknown) => unknown;
+  updateWorkspaceLabel?: (args: unknown) => unknown;
+  removeWorkspaceLabel?: (args: unknown) => unknown;
+  [key: string]: unknown;
+}
+
+export interface WorkspaceBeaconOptions {
+  workspaceHandle?: WorkspaceTitleHandle | null;
+  daemonClient?: BeaconDaemonClient | null;
+  labelPrefix?: string;
+  baseTitle?: string;
+  logger?: PluginLogger;
+}
+
+export interface BeaconSetResult {
+  labelApplied: boolean;
+  titleApplied: boolean;
+  labelName?: string;
+  title?: string;
+}
+
+export interface BeaconClearResult {
+  labelCleared: boolean;
+  titleRestored: boolean;
+}
+
+export interface BeaconBlinkHandle {
+  stop: () => void;
+  done: Promise<void>;
+}
+
+export function resolveBeaconLabelName(
+  name: string,
+  prefix: string = DEFAULT_BEACON_LABEL_PREFIX,
+): string {
+  const trimmed = (name ?? "").trim();
+  if (!prefix) return trimmed;
+  if (trimmed.toLowerCase().startsWith(prefix.toLowerCase())) return trimmed;
+  return `${prefix}${trimmed}`;
+}
+
+export function normalizeBeaconColor(color: string | undefined): string | undefined {
+  if (!color) return undefined;
+  const normalized = color.trim().toLowerCase();
+  if ((BEACON_COLORS as readonly string[]).includes(normalized)) return normalized;
+  return undefined;
+}
+
+function isFunction(value: unknown): value is (...args: never[]) => unknown {
+  return typeof value === "function";
+}
+
+async function safeInvoke(
+  fn: () => unknown,
+  logger?: PluginLogger,
+): Promise<boolean> {
+  try {
+    await fn();
+    return true;
+  } catch (err) {
+    logger?.debug?.(
+      `WorkspaceBeacon host call failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+}
+
+function toTimerKey(workspaceId: string | undefined): string {
+  return workspaceId ?? "__default__";
+}
+
+export class WorkspaceBeacon {
+  private workspaceHandle?: WorkspaceTitleHandle | null;
+  private daemonClient?: BeaconDaemonClient | null;
+  private labelPrefix: string;
+  private baseTitle?: string;
+  private logger?: PluginLogger;
+  private originalTitles = new Map<string, string>();
+  private blinkTimers = new Map<string, { timer: ReturnType<typeof setInterval>; finish: () => void }>();
+
+  constructor(options: WorkspaceBeaconOptions = {}) {
+    this.workspaceHandle = options.workspaceHandle ?? null;
+    this.daemonClient = options.daemonClient ?? null;
+    this.labelPrefix = options.labelPrefix ?? DEFAULT_BEACON_LABEL_PREFIX;
+    this.baseTitle = options.baseTitle;
+    this.logger = options.logger;
+  }
+
+  setOptions(options: Partial<WorkspaceBeaconOptions>): void {
+    if ("workspaceHandle" in options) this.workspaceHandle = options.workspaceHandle ?? null;
+    if ("daemonClient" in options) this.daemonClient = options.daemonClient ?? null;
+    if (options.labelPrefix !== undefined) this.labelPrefix = options.labelPrefix;
+    if (options.baseTitle !== undefined) this.baseTitle = options.baseTitle;
+    if (options.logger !== undefined) this.logger = options.logger;
+  }
+
+  get activeBlinks(): number {
+    return this.blinkTimers.size;
+  }
+
+  async set(options: BeaconSetOptions): Promise<BeaconSetResult> {
+    const result: BeaconSetResult = { labelApplied: false, titleApplied: false };
+    try {
+      const workspaceId = options.workspaceId;
+      const labelName = options.name ? resolveBeaconLabelName(options.name, this.labelPrefix) : undefined;
+      result.labelName = labelName;
+
+      if (workspaceId && labelName) {
+        result.labelApplied = await this.applyLabel(workspaceId, labelName, options.color);
+      }
+
+      const title = this.resolveTitle(options);
+      if (title !== undefined) {
+        result.titleApplied = await this.applyTitle(workspaceId, title);
+        if (result.titleApplied) result.title = title;
+      }
+    } catch (err) {
+      this.logger?.debug?.(
+        `WorkspaceBeacon.set failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    return result;
+  }
+
+  blink(options: BeaconBlinkOptions): BeaconBlinkHandle {
+    const intervalMs = Math.max(50, options.intervalMs ?? 3000);
+    const totalRounds = options.rounds ?? Number.POSITIVE_INFINITY;
+    const workspaceId = options.workspaceId ?? options.a.workspaceId ?? options.b.workspaceId;
+    const key = toTimerKey(workspaceId);
+    this.stopBlink(key);
+    let stopped = false;
+    let settled = false;
+    let timer: ReturnType<typeof setInterval> | undefined;
+    let resolveDone!: () => void;
+    const done = new Promise<void>((resolve) => {
+      resolveDone = resolve;
+    });
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearInterval(timer);
+      const current = this.blinkTimers.get(key);
+      if (current?.finish === finish) this.blinkTimers.delete(key);
+      if (options.restoreOnDone) {
+        void this.clear({
+          workspaceId,
+          name: options.a.name ?? options.b.name,
+          restoreTitle: true,
+        }).catch((err) =>
+          this.logger?.debug?.(
+            `WorkspaceBeacon blink restore failed: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+        );
+      }
+      resolveDone();
+    };
+
+    try {
+      const states: BeaconLabelState[] = [options.a, options.b];
+      const tick = () => {
+        if (stopped) {
+          finish();
+          return;
+        }
+        if (count >= totalRounds) {
+          finish();
+          return;
+        }
+        const state = states[count % 2];
+        count += 1;
+        void this.set({ ...state, workspaceId: state.workspaceId ?? workspaceId ?? "" }).catch((err) =>
+          this.logger?.debug?.(
+            `WorkspaceBeacon blink tick failed: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+        );
+        if (count >= totalRounds) {
+          finish();
+        }
+      };
+      let count = 0;
+      void this.set({ ...states[0], workspaceId: states[0].workspaceId ?? workspaceId ?? "" }).catch(
+        (err) =>
+          this.logger?.debug?.(
+            `WorkspaceBeacon blink tick failed: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+      );
+      count = 1;
+      if (count >= totalRounds) {
+        finish();
+      } else {
+        timer = setInterval(tick, intervalMs);
+        this.blinkTimers.set(key, { timer, finish });
+      }
+    } catch (err) {
+      this.logger?.debug?.(
+        `WorkspaceBeacon blink setup failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      finish();
+    }
+
+    return {
+      stop: () => {
+        stopped = true;
+        finish();
+      },
+      done,
+    };
+  }
+
+  async clear(options: BeaconClearOptions = {}): Promise<BeaconClearResult> {
+    const result: BeaconClearResult = { labelCleared: false, titleRestored: false };
+    try {
+      this.stopBlink(toTimerKey(options.workspaceId));
+      if (options.workspaceId && options.name) {
+        result.labelCleared = await this.detachLabel(
+          options.workspaceId,
+          resolveBeaconLabelName(options.name, this.labelPrefix),
+        );
+      } else if (options.workspaceId && !options.name) {
+        result.labelCleared = false;
+      }
+      if (options.restoreTitle !== false) {
+        result.titleRestored = await this.restoreTitle(options.workspaceId);
+      }
+    } catch (err) {
+      this.logger?.debug?.(
+        `WorkspaceBeacon.clear failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    return result;
+  }
+
+  stopAll(): void {
+    for (const entry of this.blinkTimers.values()) {
+      clearInterval(entry.timer);
+      try {
+        entry.finish();
+      } catch (err) {
+        this.logger?.debug?.(
+          `WorkspaceBeacon stopAll finish failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+    this.blinkTimers.clear();
+  }
+
+  private resolveTitle(options: BeaconLabelState): string | undefined {
+    if (options.title !== undefined) return options.title;
+    if (options.titleSuffix === undefined) return undefined;
+    const base = this.originalTitles.get(options.workspaceId ?? "") ?? this.baseTitle ?? "";
+    return `${base}${options.titleSuffix}`;
+  }
+
+  private async applyLabel(workspaceId: string, labelName: string, color?: string): Promise<boolean> {
+    const client = this.daemonClient;
+    if (!client || !isFunction(client.setWorkspaceLabel)) return false;
+    const label: Record<string, string> = { name: labelName };
+    const normalized = normalizeBeaconColor(color);
+    if (normalized) label.color = normalized;
+    else if (color) label.color = color;
+    return safeInvoke(
+      () =>
+        (client.setWorkspaceLabel as (args: unknown) => unknown)({
+          workspaceId,
+          label,
+          assigned: true,
+        }),
+      this.logger,
+    );
+  }
+
+  private async detachLabel(workspaceId: string, labelName: string): Promise<boolean> {
+    const client = this.daemonClient as BeaconDaemonClient | null | undefined;
+    if (!client) return false;
+    try {
+      if (isFunction(client.setWorkspaceLabel)) {
+        return await safeInvoke(
+          () =>
+            (client.setWorkspaceLabel as (args: unknown) => unknown)({
+              workspaceId,
+              label: { name: labelName },
+              assigned: false,
+            }),
+          this.logger,
+        );
+      }
+      if (isFunction(client.removeWorkspaceLabel)) {
+        return await safeInvoke(
+          () =>
+            (client.removeWorkspaceLabel as (args: unknown) => unknown)({
+              workspaceId,
+              name: labelName,
+            }),
+          this.logger,
+        );
+      }
+      return false;
+    } catch (err) {
+      this.logger?.debug?.(
+        `WorkspaceBeacon detachLabel failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return false;
+    }
+  }
+
+  setOriginalTitle(workspaceId: string, title: string): void {
+    this.originalTitles.set(workspaceId, title);
+  }
+
+  hasOriginalTitle(workspaceId: string): boolean {
+    return this.originalTitles.has(workspaceId);
+  }
+
+  getOriginalTitle(workspaceId: string): string | undefined {
+    return this.originalTitles.get(workspaceId);
+  }
+
+  private async applyTitle(workspaceId: string | undefined, title: string): Promise<boolean> {
+    const handle = this.workspaceHandle;
+    if (!handle || !isFunction(handle.setTitle)) return false;
+    const key = workspaceId ?? "";
+    if (!this.originalTitles.has(key)) {
+      if (this.baseTitle !== undefined) {
+        this.originalTitles.set(key, this.baseTitle);
+      }
+    }
+    return safeInvoke(() => (handle.setTitle as (t: string) => unknown)(title), this.logger);
+  }
+
+  private async restoreTitle(workspaceId: string | undefined): Promise<boolean> {
+    const handle = this.workspaceHandle;
+    if (!handle || !isFunction(handle.setTitle)) return false;
+    const key = workspaceId ?? "";
+    const original = this.originalTitles.get(key) ?? this.baseTitle;
+    if (original === undefined) return false;
+    const ok = await safeInvoke(
+      () => (handle.setTitle as (t: string) => unknown)(original),
+      this.logger,
+    );
+    if (ok) {
+      this.originalTitles.delete(key);
+      if (this.baseTitle === original) {
+        this.baseTitle = undefined;
+      }
+    }
+    return ok;
+  }
+
+  private stopBlink(key: string): void {
+    const entry = this.blinkTimers.get(key);
+    if (entry) {
+      clearInterval(entry.timer);
+      this.blinkTimers.delete(key);
+      try {
+        entry.finish();
+      } catch (err) {
+        this.logger?.debug?.(
+          `WorkspaceBeacon stopBlink finish failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+}
+
+export function createWorkspaceBeacon(options: WorkspaceBeaconOptions = {}): WorkspaceBeacon {
+  return new WorkspaceBeacon(options);
+}

package/shared/resources.ts

@@ -0,0 +1,289 @@
+import {
+  defineContract,
+  defineSettingsContract,
+} from "paseo-plugin-helper/shared";
+import { z } from "zod";
+
+export const SLASH_VERSION = "0.1.0";
+
+export const SUGGESTED_PREFIX = "slash-";
+
+// The host owns the surface registry and exposes no enumeration to plugins, so
+// this list is maintained by hand from in-repo surface registrations and can
+// drift as plugins add surfaces (issue #186).
+export const KNOWN_OPEN_TARGETS: string[] = ["slash-console", "main", "approvals", "paseo-top-dashboard"];
+
+export const COMMAND_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export const COMMAND_NAME_HINT =
+  "Lowercase letters, digits, and dashes; must start with a letter or digit.";
+
+export const SendActionSchema = z.object({
+  verb: z.literal("send"),
+  template: z.string().min(1).max(8000),
+});
+export type SendAction = z.infer<typeof SendActionSchema>;
+
+export const OpenActionSchema = z.object({
+  verb: z.literal("open"),
+  target: z.string().min(1).max(200),
+});
+export type OpenAction = z.infer<typeof OpenActionSchema>;
+
+export const RpcActionSchema = z.object({
+  verb: z.literal("rpc"),
+  operation: z.string().min(1).max(200),
+  params: z.record(z.string(), z.unknown()).default({}),
+});
+export type RpcAction = z.infer<typeof RpcActionSchema>;
+
+export const SlashActionSchema = z.discriminatedUnion("verb", [
+  SendActionSchema,
+  OpenActionSchema,
+  RpcActionSchema,
+]);
+export type SlashAction = z.infer<typeof SlashActionSchema>;
+
+export const SlashCommandSchema = z.object({
+  name: z.string().min(1).max(64).regex(COMMAND_NAME_PATTERN),
+  title: z.string().min(1).max(120),
+  description: z.string().max(500).default(""),
+  enabled: z.boolean().default(true),
+  action: SlashActionSchema,
+});
+export type SlashCommand = z.infer<typeof SlashCommandSchema>;
+
+export const SlashSettingsSchema = z.object({
+  prefix: z.string().max(32).default("slash-"),
+  commands: z.array(SlashCommandSchema).default([]),
+});
+export type SlashSettings = z.infer<typeof SlashSettingsSchema>;
+
+export const slashSettingsContract = defineSettingsContract({
+  name: "slash.settings",
+  schema: SlashSettingsSchema,
+  description: "S/ash command repository and custom command facilities",
+});
+
+export const CommandBundleSchema = z.object({
+  bundle: z.literal("slash-commands"),
+  version: z.literal(1),
+  commands: z.array(SlashCommandSchema).min(1).max(200),
+});
+export type CommandBundle = z.infer<typeof CommandBundleSchema>;
+
+export function interpolateTemplate(template: string, args: string): string {
+  return template.includes("{args}")
+    ? template.replaceAll("{args}", args)
+    : args
+      ? `${template} ${args}`
+      : template;
+}
+
+export function withPrefix(prefix: string, name: string): string {
+  return prefix ? `${prefix}${name}` : name;
+}
+
+export const SEED_COMMANDS: SlashCommand[] = [
+  {
+    name: "review",
+    title: "Review",
+    description: "Send a code-review prompt for the current diff",
+    enabled: true,
+    action: { verb: "send", template: "Review the current changes: {args}" },
+  },
+  {
+    name: "console",
+    title: "Console",
+    description: "Open the S/ash output console",
+    enabled: true,
+    action: { verb: "open", target: "slash-console" },
+  },
+  {
+    name: "ping",
+    title: "Ping",
+    description: "Safe no-op backend operation proving the rpc verb",
+    enabled: true,
+    action: { verb: "rpc", operation: "slash.ping", params: {} },
+  },
+  {
+    name: "orchestrate",
+    title: "Orchestrate",
+    description: "Hand the orchestrator role to this agent via the forgejo hook",
+    enabled: true,
+    action: { verb: "rpc", operation: "slash.orchestrate", params: {} },
+  },
+];
+
+export type SlashVerb = SlashAction["verb"];
+
+export interface SlashCommandDraft {
+  name: string;
+  title: string;
+  description: string;
+  enabled: boolean;
+  verb: SlashVerb;
+  template: string;
+  target: string;
+  operation: string;
+}
+
+export type CommandDraftErrorField = "name" | "title" | "description" | "action";
+export type CommandDraftErrors = Partial<Record<CommandDraftErrorField, string>>;
+
+export type CommandDraftWarningField = "action";
+export type CommandDraftWarnings = Partial<Record<CommandDraftWarningField, string>>;
+
+/** Allowlisted rpc operations and known open-surface ids used for live validation. */
+export interface OperationCatalog {
+  rpc?: readonly string[];
+  open?: readonly string[];
+}
+
+export function emptyCommandDraft(): SlashCommandDraft {
+  return {
+    name: "",
+    title: "",
+    description: "",
+    enabled: true,
+    verb: "send",
+    template: "",
+    target: "",
+    operation: "",
+  };
+}
+
+export function draftFromCommand(command: SlashCommand): SlashCommandDraft {
+  const draft: SlashCommandDraft = {
+    ...emptyCommandDraft(),
+    name: command.name,
+    title: command.title,
+    description: command.description,
+    enabled: command.enabled,
+    verb: command.action.verb,
+  };
+  if (command.action.verb === "send") draft.template = command.action.template;
+  else if (command.action.verb === "open") draft.target = command.action.target;
+  else draft.operation = command.action.operation;
+  return draft;
+}
+
+export function commandFromDraft(draft: SlashCommandDraft): SlashCommand {
+  const base = {
+    name: draft.name.trim(),
+    title: draft.title.trim(),
+    description: draft.description,
+    enabled: draft.enabled,
+  };
+  if (draft.verb === "send") return { ...base, action: { verb: "send", template: draft.template } };
+  if (draft.verb === "open") return { ...base, action: { verb: "open", target: draft.target } };
+  return { ...base, action: { verb: "rpc", operation: draft.operation, params: {} } };
+}
+
+export function validateCommandDraft(
+  draft: SlashCommandDraft,
+  takenNames: readonly string[] = [],
+  catalog: OperationCatalog = {},
+): { errors: CommandDraftErrors; warnings: CommandDraftWarnings; command?: SlashCommand } {
+  const parsed = SlashCommandSchema.safeParse(commandFromDraft(draft));
+  if (!parsed.success) {
+    const errors: CommandDraftErrors = {};
+    for (const issue of parsed.error.issues) {
+      const key = issue.path[0];
+      if (key === "name" || key === "title" || key === "description") {
+        errors[key] ??= issue.message;
+      } else if (key === "action") {
+        errors.action ??= issue.message;
+      }
+    }
+    return { errors, warnings: {} };
+  }
+  if (takenNames.includes(parsed.data.name)) {
+    return { errors: { name: "A command with this name already exists" }, warnings: {} };
+  }
+  const warnings: CommandDraftWarnings = {};
+  if (draft.verb === "rpc" && catalog.rpc?.length && !catalog.rpc.includes(draft.operation.trim())) {
+    return {
+      errors: { action: `Unknown RPC operation; allowlisted: ${catalog.rpc.join(", ")}` },
+      warnings,
+    };
+  }
+  if (draft.verb === "open" && catalog.open?.length && !catalog.open.includes(draft.target.trim())) {
+    warnings.action = `Unknown surface id; the host does not expose its registry. Known: ${catalog.open.join(", ")}`;
+  }
+  return { errors: {}, warnings, command: parsed.data };
+}
+
+export function upsertCommand(
+  commands: readonly SlashCommand[],
+  originalName: string | null,
+  next: SlashCommand,
+): SlashCommand[] {
+  if (originalName === null) return [...commands, next];
+  return commands.map((command) => (command.name === originalName ? next : command));
+}
+
+export function removeCommandByName(commands: readonly SlashCommand[], name: string): SlashCommand[] {
+  return commands.filter((command) => command.name !== name);
+}
+
+export function missingCatalogCommands(
+  commands: readonly SlashCommand[],
+  catalog: readonly SlashCommand[],
+): SlashCommand[] {
+  const present = new Set(commands.map((command) => command.name));
+  return catalog.filter((command) => !present.has(command.name));
+}
+
+export function actionSummary(action: SlashAction): string {
+  if (action.verb === "send") return "send";
+  if (action.verb === "open") return `open → ${action.target}`;
+  return `rpc → ${action.operation}`;
+}
+
+export const listCommandsRpc = defineContract({
+  name: "slash.commands.list",
+  description: "List effective slash commands with prefix applied",
+  input: z.object({}).default({}),
+  output: z.object({ commands: z.array(SlashCommandSchema) }),
+});
+
+export const catalogRpc = defineContract({
+  name: "slash.catalog.list",
+  description: "List the shipped seed command catalog without touching settings",
+  input: z.object({}).default({}),
+  output: z.object({ commands: z.array(SlashCommandSchema) }),
+});
+
+export const operationsListRpc = defineContract({
+  name: "slash.operations.list",
+  description: "List allowlisted rpc operations and the curated known open-surface ids",
+  input: z.object({}).default({}),
+  output: z.object({ rpc: z.array(z.string()), open: z.array(z.string()) }),
+});
+
+export const runCommandRpc = defineContract({
+  name: "slash.commands.run",
+  description: "Run one slash command by name; send/open resolve client-side, rpc runs here",
+  input: z.object({ name: z.string(), args: z.string().default(""), agentId: z.string().optional() }),
+  output: z.object({
+    verb: z.enum(["send", "open", "rpc"]),
+    prompt: z.string().optional(),
+    target: z.string().optional(),
+    result: z.unknown().optional(),
+  }),
+});
+
+export const exportBundleRpc = defineContract({
+  name: "slash.bundle.export",
+  description: "Export enabled commands as a shareable bundle document",
+  input: z.object({}).default({}),
+  output: z.object({ bundle: CommandBundleSchema }),
+});
+
+export const importBundleRpc = defineContract({
+  name: "slash.bundle.import",
+  description: "Validate and merge a shared command bundle into settings",
+  input: z.object({ bundle: CommandBundleSchema, overwrite: z.boolean().default(false) }),
+  output: z.object({ commands: z.array(SlashCommandSchema) }),
+});