@xpufx/paseo-slash 0.1.0

package/client/vendor/paseo-plugin-helper/utils/clipboard.ts

@@ -0,0 +1,149 @@
+import type { HostToast } from "../host";
+import { getOptionalClientHost } from "../host";
+
+export interface CopyToClipboardOptions {
+  toast?: HostToast;
+  toastMessage?: string;
+}
+
+export type ClipboardTier = "navigator" | "host" | "rnAsync" | "rnSync" | "execCommand";
+
+export interface ClipboardEnvironment {
+  hasNavigatorClipboard: boolean;
+  hasHostCopyText: boolean;
+  hasRnClipboard: boolean;
+  hasRnSetStringAsync: boolean;
+  isDom: boolean;
+}
+
+/**
+ * Deterministic tier order for an explicit copy.
+ *
+ * Web's `navigator.clipboard.writeText` is the only API that rejects when the
+ * clipboard did not change, so it leads. The synchronous
+ * `react-native-web` `Clipboard.setString` reports success even when its
+ * `document.execCommand("copy")` fails, which leaves the previous clipboard
+ * item in place while the UI claims success (xpufx-org/paseo#278); it is only
+ * usable off-DOM (native), where it is the real platform clipboard. In a DOM
+ * the checked `execCommand` fallback is preferred to that unverifiable path.
+ */
+export function clipboardTierOrder(env: ClipboardEnvironment): ClipboardTier[] {
+  const tiers: ClipboardTier[] = [];
+  if (env.hasNavigatorClipboard) tiers.push("navigator");
+  if (env.hasHostCopyText) tiers.push("host");
+  if (env.hasRnSetStringAsync) {
+    tiers.push("rnAsync");
+  } else if (env.hasRnClipboard && !env.isDom) {
+    tiers.push("rnSync");
+  }
+  tiers.push("execCommand");
+  return tiers;
+}
+
+/**
+ * Robust cross-platform clipboard copy helper for Paseo plugins.
+ * Works seamlessly across React Native (mobile), web, and desktop.
+ *
+ * Tier order comes from `clipboardTierOrder`; every tier reports failure
+ * honestly so a denied or blocked write never leaves the previous clipboard
+ * item behind under a fake success.
+ */
+export async function copyToClipboard(
+  text: string,
+  options?: CopyToClipboardOptions,
+): Promise<boolean> {
+  if (text === null || text === undefined) return false;
+  const str = String(text);
+
+  const globalObj = typeof globalThis !== "undefined" ? (globalThis as any) : {};
+
+  let rn: any;
+  try {
+    rn = require("react-native");
+  } catch {
+    // Ignore require error if not in RN context
+  }
+  const rnClipboard = rn?.Clipboard;
+  const rnSetStringAsync =
+    typeof rnClipboard?.setStringAsync === "function" ? rnClipboard.setStringAsync : undefined;
+  const rnSetString =
+    typeof rnClipboard?.setString === "function" ? rnClipboard.setString : undefined;
+  const copyText = getOptionalClientHost()?.copyText;
+
+  const isDom =
+    typeof globalObj.document !== "undefined" &&
+    typeof globalObj.document?.createElement === "function";
+
+  const tiers = clipboardTierOrder({
+    hasNavigatorClipboard: Boolean(globalObj.navigator?.clipboard?.writeText),
+    hasHostCopyText: Boolean(copyText),
+    hasRnClipboard: Boolean(rnSetStringAsync ?? rnSetString),
+    hasRnSetStringAsync: Boolean(rnSetStringAsync),
+    isDom,
+  });
+
+  let success = false;
+  for (const tier of tiers) {
+    if (success) break;
+    try {
+      switch (tier) {
+        case "navigator":
+          await globalObj.navigator.clipboard.writeText(str);
+          success = true;
+          break;
+        case "host":
+          if (copyText) {
+            await copyText(str);
+            success = true;
+          }
+          break;
+        case "rnAsync":
+          // Expo's async API returns a boolean; a rejected promise falls through.
+          success = (await rnSetStringAsync(str)) !== false;
+          break;
+        case "rnSync":
+          // Only reached off-DOM, where this is the native platform clipboard.
+          rnSetString(str);
+          success = true;
+          break;
+        case "execCommand": {
+          const doc = globalObj.document;
+          if (doc?.createElement && doc?.body) {
+            const textarea = doc.createElement("textarea");
+            textarea.value = str;
+            textarea.style.position = "fixed";
+            textarea.style.opacity = "0";
+            textarea.style.left = "-9999px";
+            doc.body.appendChild(textarea);
+            textarea.focus();
+            textarea.select();
+            const res = doc.execCommand("copy");
+            doc.body.removeChild(textarea);
+            success = res === true;
+          }
+          break;
+        }
+      }
+    } catch {
+      // Tier failed; try the next one.
+    }
+  }
+
+  if (success && options?.toast) {
+    try {
+      const toastAny = options.toast as any;
+      if (typeof toastAny.copied === "function") {
+        toastAny.copied(options.toastMessage);
+      } else if (typeof toastAny.show === "function") {
+        const msg = options.toastMessage
+          ? `Copied ${options.toastMessage} to clipboard`
+          : "Copied to clipboard";
+        toastAny.show(msg, { variant: "success" });
+      }
+    } catch {
+      // Ignore toast failure
+    }
+  }
+
+  return success;
+}

package/client/vendor/paseo-plugin-helper/utils/haptics.ts

@@ -0,0 +1,34 @@
+export type HapticFeedbackType =
+  | "light"
+  | "medium"
+  | "heavy"
+  | "success"
+  | "warning"
+  | "error";
+
+const PATTERNS: Record<HapticFeedbackType, number | number[]> = {
+  light: 10,
+  medium: 25,
+  heavy: 45,
+  success: [15, 40, 20],
+  warning: [30, 50, 30],
+  error: [40, 60, 40, 60, 40],
+};
+
+/**
+ * Cross-platform haptic feedback helper for Paseo plugins.
+ * Supports web vibration API and graceful fallback when vibration is unavailable.
+ */
+export function triggerHaptic(type: HapticFeedbackType = "light"): boolean {
+  try {
+    const globalObj = typeof globalThis !== "undefined" ? (globalThis as any) : {};
+    const nav = globalObj.navigator;
+    if (typeof nav?.vibrate === "function") {
+      const pattern = PATTERNS[type] ?? 15;
+      return Boolean(nav.vibrate(pattern));
+    }
+  } catch {
+    // Ignore environments where vibration permissions are denied or unavailable
+  }
+  return false;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@xpufx/paseo-slash",
+  "private": false,
+  "license": "MIT",
+  "version": "0.1.0",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "files": [
+    "paseo-plugin.json",
+    "README.md",
+    "LICENSE",
+    "client",
+    "server",
+    "shared",
+    "docs",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/*.test.mjs",
+    "!**/.DS_Store"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xpufx/paseo.git"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,4 @@
+{
+  "id": "slash",
+  "requirements": { "paseo": ">=0.8.0" }
+}

package/server/orchestrate.ts

@@ -0,0 +1,81 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_HOOK_URL = "http://127.0.0.1:8099";
+
+const HOOK_TIMEOUT_MS = 10_000;
+
+function resolveHookUrl(): string {
+  return process.env.PASEO_FORGEJO_HOOK_URL?.trim() || DEFAULT_HOOK_URL;
+}
+
+function resolveSecretFile(): string {
+  const override = process.env.PASEO_FORGEJO_HOOK_SECRET_FILE?.trim();
+  if (override) return override;
+  return join(process.env.HOME || homedir(), ".paseo", "forgejo-hook.secret");
+}
+
+function readSecret(): string {
+  const file = resolveSecretFile();
+  try {
+    const secret = readFileSync(file, "utf8").trim();
+    if (secret) return secret;
+  } catch {
+    // Missing or unreadable file: fall back to the hook's own env convention.
+  }
+  const fromEnv = process.env.FORGEJO_WEBHOOK_SECRET?.trim();
+  if (fromEnv) return fromEnv;
+  throw new Error(`forgejo hook secret unavailable at ${file}`);
+}
+
+function errorReason(status: number, statusText: string, payload: unknown): string {
+  if (payload && typeof payload === "object" && "error" in payload) {
+    const reason = (payload as { error?: unknown }).error;
+    if (typeof reason === "string" && reason.trim()) return reason.trim();
+  }
+  if (typeof payload === "string" && payload.trim()) return payload.trim();
+  return statusText || `hook refused the handover (${status})`;
+}
+
+/**
+ * Deterministic orchestrator handover: POSTs the caller's agent id to the
+ * forgejo hook control endpoint. Fails closed on missing secret, an
+ * unreachable hook, or a non-2xx rejection; the secret is never surfaced.
+ */
+export async function orchestrateHandover(agentId: string): Promise<unknown> {
+  const id = agentId?.trim();
+  if (!id) throw new Error("orchestrate requires a caller agent id");
+
+  const secret = readSecret();
+  const url = `${resolveHookUrl().replace(/\/+$/, "")}/orchestrate`;
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${secret}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ agentId: id }),
+      signal: AbortSignal.timeout(HOOK_TIMEOUT_MS),
+    });
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`orchestrate failed: forgejo hook unreachable at ${url} (${detail})`);
+  }
+
+  const text = await response.text().catch(() => "");
+  let payload: unknown = null;
+  try {
+    payload = text ? JSON.parse(text) : null;
+  } catch {
+    payload = text;
+  }
+
+  if (!response.ok) {
+    throw new Error(`orchestrate rejected (${response.status}): ${errorReason(response.status, response.statusText, payload)}`);
+  }
+  return payload ?? { ok: true };
+}

package/server/resources.ts

@@ -0,0 +1,132 @@
+import { PluginStorage, createPluginLogger } from "paseo-plugin-helper/server";
+import {
+  KNOWN_OPEN_TARGETS,
+  SEED_COMMANDS,
+  interpolateTemplate,
+  slashSettingsContract,
+  type CommandBundle,
+  type SlashCommand,
+  type SlashSettings,
+} from "../shared/resources";
+import { PLUGIN_VERSION as SLASH_PLUGIN_VERSION } from "../shared/version";
+import { orchestrateHandover } from "./orchestrate";
+
+export const log = createPluginLogger("slash", { version: SLASH_PLUGIN_VERSION });
+
+const DEFAULTS: SlashSettings = { prefix: "slash-", commands: SEED_COMMANDS };
+
+const settingsStorage = new PluginStorage<SlashSettings>("slash", "settings.json", {
+  schema: slashSettingsContract.schema,
+});
+
+async function readSettings(): Promise<SlashSettings> {
+  const data = await settingsStorage.readAsync();
+  if (!data.commands || data.commands.length === 0) {
+    return { ...data, commands: SEED_COMMANDS };
+  }
+  return data;
+}
+
+export async function handleGetSettings(): Promise<SlashSettings> {
+  return readSettings();
+}
+
+export async function handleUpdateSettings(patch: Partial<SlashSettings>): Promise<SlashSettings> {
+  if (patch.prefix !== undefined && !/^[a-z0-9-]*$/.test(patch.prefix)) {
+    throw new Error("prefix may only contain lowercase letters, digits, and dashes");
+  }
+  return settingsStorage.updateAsync((prev) => ({ ...prev, ...patch }));
+}
+
+export async function handleResetSettings(): Promise<SlashSettings> {
+  settingsStorage.reset();
+  return DEFAULTS;
+}
+
+export async function handleListCommands(): Promise<{ commands: SlashCommand[] }> {
+  const settings = await readSettings();
+  return { commands: settings.commands.filter((c) => c.enabled) };
+}
+
+export function handleListCatalog(): { commands: SlashCommand[] } {
+  return { commands: SEED_COMMANDS };
+}
+
+export function handleListOperations(): { rpc: string[]; open: string[] } {
+  return { rpc: allowedOperations(), open: [...KNOWN_OPEN_TARGETS] };
+}
+
+export interface OperationContext {
+  agentId?: string;
+}
+
+type OperationHandler = (params: Record<string, unknown>, context: OperationContext) => unknown;
+
+const SAFE_OPERATIONS: Record<string, OperationHandler> = {
+  "slash.ping": () => ({ ok: true, version: SLASH_PLUGIN_VERSION }),
+  "slash.echo": (params) => ({ echo: params }),
+  "slash.orchestrate": (_params, context) => {
+    if (!context.agentId) throw new Error("orchestrate requires a caller agent id");
+    return orchestrateHandover(context.agentId);
+  },
+};
+
+export function allowedOperations(): string[] {
+  return Object.keys(SAFE_OPERATIONS);
+}
+
+export async function runOperation(
+  operation: string,
+  params: Record<string, unknown>,
+  context: OperationContext = {},
+): Promise<unknown> {
+  const handler = SAFE_OPERATIONS[operation];
+  if (!handler) {
+    throw new Error(`rpc operation not allowlisted: ${operation}`);
+  }
+  return handler(params, context);
+}
+
+export async function handleRunCommand(input: { name: string; args: string; agentId?: string }) {
+  const settings = await readSettings();
+  const command = settings.commands.find((c) => c.enabled && c.name === input.name);
+  if (!command) {
+    throw new Error(`unknown or disabled command: ${input.name}`);
+  }
+  if (command.action.verb === "send") {
+    return { verb: "send" as const, prompt: interpolateTemplate(command.action.template, input.args) };
+  }
+  if (command.action.verb === "open") {
+    return { verb: "open" as const, target: command.action.target };
+  }
+  const result = await runOperation(command.action.operation, command.action.params ?? {}, {
+    agentId: input.agentId,
+  });
+  return { verb: "rpc" as const, result };
+}
+
+export async function handleExportBundle(): Promise<{ bundle: CommandBundle }> {
+  const settings = await readSettings();
+  return {
+    bundle: {
+      bundle: "slash-commands",
+      version: 1,
+      commands: settings.commands.filter((c) => c.enabled),
+    },
+  };
+}
+
+export async function handleImportBundle(input: {
+  bundle: CommandBundle;
+  overwrite: boolean;
+}): Promise<{ commands: SlashCommand[] }> {
+  const settings = await readSettings();
+  const existing = new Map(settings.commands.map((c) => [c.name, c]));
+  for (const incoming of input.bundle.commands) {
+    if (existing.has(incoming.name) && !input.overwrite) continue;
+    existing.set(incoming.name, incoming);
+  }
+  const commands = [...existing.values()];
+  await settingsStorage.updateAsync((prev) => ({ ...prev, commands }));
+  return { commands };
+}

package/server/vendor/paseo-plugin-helper/agent.ts

@@ -0,0 +1,85 @@
+import { safeExec } from "./process";
+
+export interface AgentIdentity {
+  id?: string;
+  name?: string;
+  model?: string;
+  provider?: string;
+  repo?: string;
+  branch?: string;
+  envelopeText?: string;
+}
+
+export interface AgentIdentityOptions {
+  timeoutMs?: number;
+  envelopeCommand?: string;
+}
+
+const ENV_KEYS = [
+  "AGENT_ID",
+  "AGENT_NAME",
+  "AGENT_MODEL",
+  "AGENT_PROVIDER",
+  "PASEO_AGENT_ID",
+] as const;
+
+function readEnvIdentity(env: NodeJS.ProcessEnv = process.env): AgentIdentity | null {
+  const id = env.PASEO_AGENT_ID || env.AGENT_ID || undefined;
+  const name = env.AGENT_NAME || undefined;
+  const model = env.AGENT_MODEL || undefined;
+  const provider = env.AGENT_PROVIDER || undefined;
+  if (!id && !name && !model && !provider) return null;
+  return { id, name, model, provider };
+}
+
+function normalizeEnvelopeJson(raw: unknown): AgentIdentity | null {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw as Record<string, unknown>;
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0 ? v : undefined;
+  const identity: AgentIdentity = {
+    id: str(o.id) ?? str(o.agentId),
+    name: str(o.name) ?? str(o.agentName),
+    model: str(o.model),
+    provider: str(o.provider),
+    repo: str(o.repo) ?? str(o.workspace),
+    branch: str(o.branch),
+    envelopeText: str(o.envelopeText) ?? str(o.envelope),
+  };
+  if (!identity.id && !identity.name && !identity.model && !identity.provider && !identity.repo && !identity.branch) return null;
+  return identity;
+}
+
+export async function getAgentIdentity(
+  options: AgentIdentityOptions = {},
+): Promise<AgentIdentity | null> {
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const command = options.envelopeCommand ?? "xpufx-tool envelope --format json";
+  const envIdentity = readEnvIdentity();
+  void ENV_KEYS;
+  try {
+    const result = await safeExec(command, { timeoutMs });
+    if (result.code !== 0) return envIdentity;
+    const text = result.stdout.trim();
+    if (!text) return envIdentity;
+    try {
+      const parsed: unknown = JSON.parse(text);
+      const cliIdentity = normalizeEnvelopeJson(parsed);
+      if (!cliIdentity) return envIdentity;
+      if (!envIdentity) return cliIdentity;
+      return {
+        id: envIdentity.id ?? cliIdentity.id,
+        name: envIdentity.name ?? cliIdentity.name,
+        model: envIdentity.model ?? cliIdentity.model,
+        provider: envIdentity.provider ?? cliIdentity.provider,
+        repo: cliIdentity.repo,
+        branch: cliIdentity.branch,
+        envelopeText: cliIdentity.envelopeText,
+      };
+    } catch {
+      return envIdentity;
+    }
+  } catch {
+    return envIdentity;
+  }
+}