@clawstore/clawstore 1.0.0

package/src/types.ts

@@ -0,0 +1,167 @@
+// ─── Agent Manifest (agent.json) ────────────────────────────────────
+
+export interface SkillDependency {
+  id: string;
+  version: string;
+  required: boolean;
+}
+
+export interface AgentManifest {
+  id: string;
+  slug: string;
+  name: string;
+  subtitle: string;
+  description: string;
+  version: string;
+  author: string;
+  author_id?: string;
+  homepage?: string;
+  license: string;
+  price: number;
+  currency: string;
+  category: string;
+  tags: string[];
+  icon?: string;
+  screenshots?: string[];
+  openclaw_version: string;
+  entry_files: string[];
+  skills: SkillDependency[];
+  checksum?: string;
+  published_at?: string;
+  updated_at?: string;
+  source_agent_id?: string;
+  packed_at?: string;
+  packaged_by?: string;
+  detection_mode?: string;
+}
+
+// ─── Installed Agent Record ─────────────────────────────────────────
+
+export interface InstalledAgentRecord {
+  id: string;
+  name: string;
+  version: string;
+  category: string;
+  author: string;
+  enabled: boolean;
+  installed_at: string;
+  updated_at: string;
+  source: string;
+  install_path: string;
+  backup_path: string;
+  disable_backup_path?: string;
+  files: string[];
+  skills: string[];
+}
+
+export interface AgentRegistry {
+  agents: Record<string, InstalledAgentRecord>;
+}
+
+// ─── Installed Skill Record ─────────────────────────────────────────
+
+export interface InstalledSkillRecord {
+  skill_id: string;
+  version: string;
+  installed_at: string;
+  installed_by: string;
+  source: string;
+}
+
+export interface SkillRegistry {
+  skills: Record<string, InstalledSkillRecord>;
+}
+
+// ─── Install State Machine ──────────────────────────────────────────
+
+export type InstallState =
+  | "idle"
+  | "fetching_manifest"
+  | "downloading_package"
+  | "verifying_package"
+  | "checking_compatibility"
+  | "installing_skills"
+  | "installing_agent"
+  | "registering_agent"
+  | "rolling_back"
+  | "success"
+  | "failed";
+
+// ─── Pack State Machine ─────────────────────────────────────────────
+
+export type PackState =
+  | "idle"
+  | "loading_agent"
+  | "collecting_files"
+  | "detecting_skills"
+  | "awaiting_confirmation"
+  | "generating_agent_json"
+  | "packing_zip"
+  | "saving_or_uploading"
+  | "success"
+  | "failed";
+
+// ─── Plugin Config ──────────────────────────────────────────────────
+
+export interface ClawstoreConfig {
+  apiBaseUrl: string;
+  autoCheckUpdates: boolean;
+  autoInstallSkills: boolean;
+}
+
+// ─── Store API Response Types ───────────────────────────────────────
+
+export interface StoreAgentSummary {
+  id: string;
+  name: string;
+  subtitle: string;
+  author: string;
+  price: number;
+  currency: string;
+  category: string;
+  rating: number;
+  downloads: number;
+  openclaw_version: string;
+}
+
+export interface StoreAgentDetail extends StoreAgentSummary {
+  description: string;
+  tags: string[];
+  skills: SkillDependency[];
+  version: string;
+  screenshots: string[];
+  published_at: string;
+  updated_at: string;
+}
+
+export interface StoreSearchResult {
+  total: number;
+  agents: StoreAgentSummary[];
+}
+
+// ─── Diagnostic Result ──────────────────────────────────────────────
+
+export interface DiagnosticCheck {
+  label: string;
+  path?: string;
+  status: "ok" | "warn" | "fail";
+  detail?: string;
+}
+
+export interface DiagnosticReport {
+  checks: DiagnosticCheck[];
+  allOk: boolean;
+}
+
+// ─── Validation ─────────────────────────────────────────────────────
+
+export interface ValidationError {
+  field: string;
+  message: string;
+}
+
+export interface PackageValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  manifest: AgentManifest | null;
+}

package/src/utils/checksum.ts

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+export async function computeSha256(filePath: string): Promise<string> {
+  const data = await readFile(filePath);
+  const hash = createHash("sha256").update(data).digest("hex");
+  return `sha256:${hash.substring(0, 16)}`;
+}
+
+export async function computeFullSha256(filePath: string): Promise<string> {
+  const data = await readFile(filePath);
+  return createHash("sha256").update(data).digest("hex");
+}
+
+export function hashBuffer(buf: Buffer): string {
+  return createHash("sha256").update(buf).digest("hex");
+}

package/src/utils/output.ts

@@ -0,0 +1,76 @@
+/**
+ * Formatting helpers for CLI/slash command output.
+ * Follows the Clawstore output design spec: result first, details second,
+ * short text for next-step guidance.
+ */
+
+export function stepLine(step: number, total: number, label: string, status: string): string {
+  return `  [${step}/${total}] ${label} ... ${status}`;
+}
+
+export function successBanner(agentName: string, version: string, extra?: Record<string, string>): string {
+  const lines: string[] = [
+    "",
+    `  Installed: ${agentName}@${version}`,
+  ];
+  if (extra) {
+    for (const [k, v] of Object.entries(extra)) {
+      lines.push(`  ${k}: ${v}`);
+    }
+  }
+  lines.push("  Status: enabled");
+  lines.push("");
+  lines.push("  Next: start a new chat in OpenClaw to activate the new persona");
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function errorBanner(action: string, agentId: string, step: string, reason: string): string {
+  return [
+    "",
+    `  ${action} failed: ${agentId}`,
+    `  Step: ${step}`,
+    `  Reason: ${reason}`,
+    "  Next:",
+    "    1. Run `openclaw clawstore doctor`",
+    `    2. Retry \`openclaw clawstore ${action.toLowerCase()} ${agentId}\``,
+    "",
+  ].join("\n");
+}
+
+export function agentListItem(index: number, id: string, name: string, version: string, category: string, enabled: boolean): string {
+  const status = enabled ? "enabled" : "disabled";
+  return [
+    `  ${index}. ${id}`,
+    `     ${name}`,
+    `     v${version} · ${category} · ${status}`,
+  ].join("\n");
+}
+
+export function detailBlock(fields: Record<string, string | undefined>): string {
+  const lines: string[] = [""];
+  for (const [k, v] of Object.entries(fields)) {
+    if (v !== undefined) {
+      lines.push(`  ${k}: ${v}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function searchResultItem(index: number, id: string, name: string, price: number, currency: string, author: string, rating: number): string {
+  const priceStr = price === 0 ? "Free" : `${currency === "USD" ? "$" : currency}${price}`;
+  return [
+    `  ${index}. ${id}`,
+    `     ${name}`,
+    `     ${priceStr} · by ${author} · rating ${rating.toFixed(1)}`,
+  ].join("\n");
+}
+
+export function indentLines(text: string, indent: number = 2): string {
+  const pad = " ".repeat(indent);
+  return text
+    .split("\n")
+    .map((l) => (l.trim() ? `${pad}${l}` : l))
+    .join("\n");
+}

package/src/utils/zip.ts

@@ -0,0 +1,55 @@
+import AdmZip from "adm-zip";
+import { mkdir, readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { CACHE_DIR } from "../constants.js";
+
+/**
+ * Extract a ZIP to a cache directory, returning the effective package root.
+ * If the ZIP contains a single top-level directory, that directory is returned.
+ */
+export async function extractZip(zipPath: string): Promise<string> {
+  const zip = new AdmZip(zipPath);
+  const baseName = zipPath.replace(/\.zip$/i, "").split(/[\\/]/).pop()!;
+  const extractDir = join(CACHE_DIR, baseName);
+
+  await mkdir(extractDir, { recursive: true });
+  zip.extractAllTo(extractDir, true);
+
+  const children = await readdir(extractDir);
+  if (children.length === 1) {
+    const child = join(extractDir, children[0]);
+    const st = await stat(child);
+    if (st.isDirectory()) return child;
+  }
+
+  return extractDir;
+}
+
+/**
+ * Create a ZIP from a source directory, excluding hidden files and __pycache__.
+ */
+export async function createZip(sourceDir: string, outputPath: string): Promise<{ path: string; sizeBytes: number }> {
+  const zip = new AdmZip();
+
+  async function walk(dir: string) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "__pycache__" || entry.name === "node_modules") {
+        continue;
+      }
+      const fullPath = join(dir, entry.name);
+      const arcPath = relative(sourceDir, fullPath);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else {
+        zip.addLocalFile(fullPath, relative(sourceDir, dir) || undefined);
+      }
+    }
+  }
+
+  await walk(sourceDir);
+  zip.writeZip(outputPath);
+
+  const st = await stat(outputPath);
+  return { path: outputPath, sizeBytes: st.size };
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "paths": {
+      "openclaw/plugin-sdk/*": ["./typings/openclaw-plugin-sdk/*"]
+    }
+  },
+  "include": ["index.ts", "src/**/*.ts", "typings/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/typings/openclaw-plugin-sdk/core.d.ts

@@ -0,0 +1,134 @@
+/**
+ * OpenClaw Plugin SDK type stubs.
+ *
+ * These mirror the real OpenClaw plugin APIs so the plugin compiles
+ * without the actual SDK installed. When running inside OpenClaw, the real
+ * module resolution takes over.
+ */
+
+// ─── CLI Registration ────────────────────────────────────────────────
+
+/**
+ * Minimal Commander.js Command interface.
+ * At runtime, `program` is a real Commander Command instance provided by OpenClaw.
+ */
+export interface CommanderProgram {
+  command(nameAndArgs: string): CommanderProgram;
+  description(str: string): CommanderProgram;
+  option(flags: string, description?: string, defaultValue?: unknown): CommanderProgram;
+  requiredOption(flags: string, description?: string, defaultValue?: unknown): CommanderProgram;
+  argument(name: string, description?: string): CommanderProgram;
+  action(fn: (...args: any[]) => void | Promise<void>): CommanderProgram;
+  addHelpText(position: string, text: string | (() => string)): CommanderProgram;
+}
+
+export interface CliRegistrarContext {
+  program: CommanderProgram;
+  config: Record<string, unknown>;
+  workspaceDir: string;
+  logger: PluginLogger;
+}
+
+export interface CliRegistrationOptions {
+  commands: string[];
+}
+
+// ─── Slash Command ───────────────────────────────────────────────────
+
+export interface SlashCommandContext {
+  args: string;
+  channel?: string;
+  senderId?: string;
+}
+
+export interface SlashCommandRegistration {
+  name: string;
+  description: string;
+  acceptsArgs: boolean;
+  handler: (ctx: SlashCommandContext) => Promise<{ text: string }>;
+}
+
+// ─── Service ─────────────────────────────────────────────────────────
+
+export interface ServiceRegistration {
+  id: string;
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+}
+
+// ─── Tool ────────────────────────────────────────────────────────────
+
+export interface ToolRegistration {
+  name: string;
+  label?: string;
+  description: string;
+  parameters: unknown;
+  execute: (
+    toolCallId: string,
+    params: Record<string, unknown>,
+  ) => Promise<{
+    content: { type: string; text: string }[];
+    details?: unknown;
+  }>;
+}
+
+// ─── Logger ──────────────────────────────────────────────────────────
+
+export interface PluginLogger {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+  debug: (msg: string) => void;
+}
+
+// ─── Plugin API ──────────────────────────────────────────────────────
+
+export interface OpenClawPluginApi {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  source: string;
+  config: Record<string, unknown>;
+  pluginConfig: unknown;
+  runtime: Record<string, unknown>;
+  logger: PluginLogger;
+
+  registerCli(
+    registrar: (ctx: CliRegistrarContext) => void,
+    opts: CliRegistrationOptions,
+  ): void;
+
+  registerCommand(registration: SlashCommandRegistration): void;
+  registerService(registration: ServiceRegistration): void;
+  registerTool(tool: ToolRegistration, opts?: { names?: string[] }): void;
+
+  registerGatewayMethod(
+    method: string,
+    handler: (opts: { params: unknown; respond: (ok: boolean, payload?: unknown) => void }) => void,
+  ): void;
+
+  registerHttpRoute(params: unknown): void;
+  registerChannel(registration: unknown): void;
+  registerProvider(provider: unknown): void;
+  registerContextEngine(id: string, factory: unknown): void;
+  resolvePath(input: string): string;
+  on(hookName: string, handler: unknown, opts?: unknown): void;
+}
+
+// ─── Plugin Definition ───────────────────────────────────────────────
+
+export interface PluginConfigSchema<T = unknown> {
+  parse?: (value: unknown) => T;
+  safeParse?: (value: unknown) => { success: boolean; data?: T; error?: { issues: { path: unknown[]; message: string }[] } };
+  jsonSchema?: unknown;
+  uiHints?: Record<string, unknown>;
+}
+
+export interface PluginDefinition {
+  id: string;
+  name: string;
+  description: string;
+  configSchema?: PluginConfigSchema;
+  register: (api: OpenClawPluginApi) => void;
+}