@clawstore/clawstore 1.0.0

package/src/core/package-installer.ts

@@ -0,0 +1,390 @@
+import { readFile, access, cp, mkdir, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  MANIFEST_FILE,
+  REQUIRED_FILES,
+  OPTIONAL_FILES,
+  MANIFEST_REQUIRED_FIELDS,
+  INSTALL_TOTAL_STEPS,
+  UPDATE_TOTAL_STEPS,
+  DOWNLOADS_DIR,
+  DEFAULT_AGENT,
+} from "../constants.js";
+import type {
+  AgentManifest,
+  InstalledAgentRecord,
+  InstallState,
+  PackageValidationResult,
+  ValidationError,
+} from "../types.js";
+import {
+  ensureDirs,
+  loadRegistry,
+  registerAgent,
+  backupCurrentWorkspace,
+  restoreFromBackup,
+  updateAgentRecord,
+} from "./agent-manager.js";
+import { installRequiredSkills } from "./skill-installer.js";
+import { resolveWorkspace } from "./workspace.js";
+import { extractZip } from "../utils/zip.js";
+import { computeSha256 } from "../utils/checksum.js";
+import { stepLine } from "../utils/output.js";
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Manifest loading & validation ──────────────────────────────────
+
+export async function loadManifest(packagePath: string): Promise<AgentManifest> {
+  const manifestPath = join(packagePath, MANIFEST_FILE);
+  if (!(await exists(manifestPath))) {
+    throw new Error(`${MANIFEST_FILE} not found in ${packagePath}`);
+  }
+  const raw = await readFile(manifestPath, "utf-8");
+  return JSON.parse(raw) as AgentManifest;
+}
+
+export async function validatePackage(packagePath: string): Promise<PackageValidationResult> {
+  const errors: ValidationError[] = [];
+
+  let manifest: AgentManifest | null = null;
+  try {
+    manifest = await loadManifest(packagePath);
+  } catch (err) {
+    errors.push({ field: "agent.json", message: (err as Error).message });
+    return { valid: false, errors, manifest: null };
+  }
+
+  for (const f of REQUIRED_FILES) {
+    if (!(await exists(join(packagePath, f)))) {
+      errors.push({ field: f, message: `Missing required file: ${f}` });
+    }
+  }
+
+  for (const field of MANIFEST_REQUIRED_FIELDS) {
+    if (!manifest[field as keyof AgentManifest]) {
+      errors.push({ field: `agent.json.${field}`, message: `Missing required field: ${field}` });
+    }
+  }
+
+  for (const ef of manifest.entry_files ?? []) {
+    if (!(await exists(join(packagePath, ef)))) {
+      errors.push({ field: `entry_files`, message: `entry_files references missing file: ${ef}` });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, manifest };
+}
+
+// ─── Resolve package path (dir or ZIP) ──────────────────────────────
+
+export async function resolvePackagePath(pathStr: string): Promise<string> {
+  const p = join(pathStr);
+
+  const st = await stat(p);
+  if (st.isFile() && p.endsWith(".zip")) {
+    return extractZip(p);
+  }
+  if (st.isDirectory()) {
+    return p;
+  }
+
+  throw new Error(`${pathStr} is not a valid directory or ZIP file`);
+}
+
+// ─── Download package from store ────────────────────────────────────
+
+export async function downloadPackage(url: string, personaId: string): Promise<string> {
+  await mkdir(DOWNLOADS_DIR, { recursive: true });
+  const destZip = join(DOWNLOADS_DIR, `${personaId}.zip`);
+
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Download failed: HTTP ${res.status}`);
+
+  const buf = Buffer.from(await res.arrayBuffer());
+  const { writeFile } = await import("node:fs/promises");
+  await writeFile(destZip, buf);
+
+  return extractZip(destZip);
+}
+
+// ─── Install Agent (7-step flow) ────────────────────────────────────
+
+export interface InstallOptions {
+  packagePath: string;
+  force?: boolean;
+  skipSkills?: boolean;
+  /** OpenClaw agent to install into (default "main") */
+  agent?: string;
+  log: (msg: string) => void;
+}
+
+export async function installAgent(opts: InstallOptions): Promise<{
+  state: InstallState;
+  agentId?: string;
+  error?: string;
+}> {
+  const { log } = opts;
+  const agent = opts.agent ?? DEFAULT_AGENT;
+  let state: InstallState = "idle";
+
+  try {
+    await ensureDirs(agent);
+    const workspace = await resolveWorkspace(agent);
+
+    // [1/7] Resolve and load manifest
+    state = "fetching_manifest";
+    log(stepLine(1, INSTALL_TOTAL_STEPS, "Loading manifest", ""));
+    const packagePath = await resolvePackagePath(opts.packagePath);
+    const manifest = await loadManifest(packagePath);
+    const personaId = manifest.id;
+    log(stepLine(1, INSTALL_TOTAL_STEPS, "Loading manifest", "OK"));
+    log(`\n  Installing: ${manifest.name} (${personaId})`);
+    log(`  Version:    ${manifest.version}`);
+    log(`  Category:   ${manifest.category ?? "N/A"}`);
+    if (agent !== DEFAULT_AGENT) log(`  Agent:      ${agent}`);
+    log("");
+
+    // [2/7] Validate package
+    state = "verifying_package";
+    log(stepLine(2, INSTALL_TOTAL_STEPS, "Validating package", ""));
+    const validation = await validatePackage(packagePath);
+    if (!validation.valid) {
+      const reasons = validation.errors.map((e) => `    - ${e.message}`).join("\n");
+      log(stepLine(2, INSTALL_TOTAL_STEPS, "Validating package", "FAILED"));
+      log(reasons);
+      return { state: "failed", agentId: personaId, error: `Validation failed:\n${reasons}` };
+    }
+    log(stepLine(2, INSTALL_TOTAL_STEPS, "Validating package", "OK"));
+
+    // [3/7] Check existing installation
+    state = "checking_compatibility";
+    log(stepLine(3, INSTALL_TOTAL_STEPS, "Checking existing installation", ""));
+    const registry = await loadRegistry(agent);
+    if (registry.agents[personaId] && !opts.force) {
+      const existing = registry.agents[personaId];
+      log(stepLine(3, INSTALL_TOTAL_STEPS, "Checking existing installation", `FOUND (v${existing.version})`));
+      log(`\n  Agent '${personaId}' is already installed.`);
+      log(`  Use 'openclaw clawstore update ${personaId}' to update,`);
+      log(`  or add --force to reinstall.`);
+      return { state: "failed", agentId: personaId, error: "already installed" };
+    }
+    log(stepLine(3, INSTALL_TOTAL_STEPS, "Checking existing installation",
+      registry.agents[personaId] ? "FOUND (--force set, reinstalling)" : "OK (fresh install)"));
+
+    // [4/7] Backup existing workspace files
+    log(stepLine(4, INSTALL_TOTAL_STEPS, "Backing up existing files", ""));
+    const backupPath = await backupCurrentWorkspace(personaId, "install", agent);
+    log(stepLine(4, INSTALL_TOTAL_STEPS, "Backing up existing files", "OK"));
+
+    // [5/7] Install required skills
+    state = "installing_skills";
+    const skills = manifest.skills ?? [];
+    const requiredSkills = skills.filter((s) => s.required);
+    if (opts.skipSkills) {
+      log(stepLine(5, INSTALL_TOTAL_STEPS, "Checking skill dependencies", "SKIPPED (--skip-skills)"));
+    } else {
+      log(stepLine(5, INSTALL_TOTAL_STEPS, "Checking skill dependencies",
+        requiredSkills.length > 0 ? `${requiredSkills.length} required` : "OK (no dependencies)"));
+      if (requiredSkills.length > 0) {
+        const skillResult = await installRequiredSkills(skills, log, packagePath, agent);
+        if (!skillResult.allOk) {
+          log(`\n  Skill installation failed. Rolling back...`);
+          state = "rolling_back";
+          await restoreFromBackup(backupPath, agent);
+          return { state: "failed", agentId: personaId, error: "required skill installation failed" };
+        }
+      }
+    }
+
+    // [6/7] Copy files to workspace
+    state = "installing_agent";
+    log(stepLine(6, INSTALL_TOTAL_STEPS, "Installing agent files", ""));
+    const installedFiles: string[] = [];
+    for (const f of [...REQUIRED_FILES, ...OPTIONAL_FILES]) {
+      const src = join(packagePath, f);
+      if (await exists(src)) {
+        await cp(src, join(workspace, f), { force: true });
+        installedFiles.push(f);
+      }
+    }
+
+    const skillsSrc = join(packagePath, "skills");
+    if (await exists(skillsSrc)) {
+      const skillsDest = join(workspace, "skills");
+      await mkdir(skillsDest, { recursive: true });
+      const entries = await readdir(skillsSrc, { withFileTypes: true });
+      for (const entry of entries) {
+        const srcPath = join(skillsSrc, entry.name);
+        const destPath = join(skillsDest, entry.name);
+        if (entry.isDirectory()) {
+          await cp(srcPath, destPath, { recursive: true, force: true });
+          installedFiles.push(`skills/${entry.name}/`);
+        } else {
+          await cp(srcPath, destPath, { force: true });
+          installedFiles.push(`skills/${entry.name}`);
+        }
+      }
+    }
+    log(stepLine(6, INSTALL_TOTAL_STEPS, "Installing agent files", `OK (${installedFiles.length} files)`));
+
+    // [7/7] Register
+    state = "registering_agent";
+    log(stepLine(7, INSTALL_TOTAL_STEPS, "Registering agent", ""));
+    const record: InstalledAgentRecord = {
+      id: personaId,
+      name: manifest.name,
+      version: manifest.version,
+      category: manifest.category ?? "",
+      author: manifest.author ?? "",
+      enabled: true,
+      installed_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      source: packagePath,
+      install_path: workspace,
+      backup_path: backupPath,
+      files: installedFiles,
+      skills: skills.map((s) => s.id),
+    };
+    await registerAgent(record, agent);
+    log(stepLine(7, INSTALL_TOTAL_STEPS, "Registering agent", "OK"));
+
+    // Summary
+    state = "success";
+    log(`\n  Installed: ${manifest.name}@${manifest.version}`);
+    if (installedFiles.length > 0) {
+      const shown = installedFiles.slice(0, 5).join(", ");
+      const extra = installedFiles.length > 5 ? ` +${installedFiles.length - 5} more` : "";
+      log(`  Files: ${shown}${extra}`);
+    }
+    log(`  Status: enabled`);
+    if (agent !== DEFAULT_AGENT) log(`  Agent: ${agent}`);
+    log(`  Backup: ${backupPath}`);
+    log(`\n  Next: start a new chat in OpenClaw to activate the new persona\n`);
+
+    return { state: "success", agentId: personaId };
+  } catch (err) {
+    return { state: "failed", error: (err as Error).message };
+  }
+}
+
+// ─── Update Agent (5-step flow) ─────────────────────────────────────
+
+export interface UpdateOptions {
+  agentId: string;
+  packagePath: string;
+  /** OpenClaw agent to update within (default "main") */
+  agent?: string;
+  log: (msg: string) => void;
+}
+
+export async function updateAgent(opts: UpdateOptions): Promise<{
+  state: InstallState;
+  error?: string;
+}> {
+  const { agentId: personaId, log } = opts;
+  const agent = opts.agent ?? DEFAULT_AGENT;
+
+  try {
+    await ensureDirs(agent);
+    const workspace = await resolveWorkspace(agent);
+    const registry = await loadRegistry(agent);
+    const current = registry.agents[personaId];
+    if (!current) {
+      log(`\n  Agent '${personaId}' is not installed.\n`);
+      return { state: "failed", error: "not installed" };
+    }
+
+    const packagePath = await resolvePackagePath(opts.packagePath);
+    const manifest = await loadManifest(packagePath);
+
+    log(`\n  Updating: ${manifest.name}`);
+    log(`  Current version:  ${current.version}`);
+    log(`  New version:      ${manifest.version}`);
+    if (agent !== DEFAULT_AGENT) log(`  Agent:            ${agent}`);
+    log("");
+
+    // [1/5] Validate
+    log(stepLine(1, UPDATE_TOTAL_STEPS, "Validating new package", ""));
+    const validation = await validatePackage(packagePath);
+    if (!validation.valid) {
+      log(stepLine(1, UPDATE_TOTAL_STEPS, "Validating new package", "FAILED"));
+      return { state: "failed", error: "validation failed" };
+    }
+    log(stepLine(1, UPDATE_TOTAL_STEPS, "Validating new package", "OK"));
+
+    // [2/5] Check new skills
+    log(stepLine(2, UPDATE_TOTAL_STEPS, "Checking new skill dependencies", ""));
+    const oldSkills = new Set(current.skills ?? []);
+    const newSkills = new Set((manifest.skills ?? []).map((s) => s.id));
+    const addedSkills = [...newSkills].filter((s) => !oldSkills.has(s));
+    if (addedSkills.length > 0) {
+      log(stepLine(2, UPDATE_TOTAL_STEPS, "Checking new skill dependencies", `${addedSkills.length} new`));
+      for (const sid of addedSkills) log(`    + ${sid}`);
+    } else {
+      log(stepLine(2, UPDATE_TOTAL_STEPS, "Checking new skill dependencies", "OK (no new)"));
+    }
+
+    // [3/5] Backup
+    log(stepLine(3, UPDATE_TOTAL_STEPS, "Backing up current version", ""));
+    const backupPath = await backupCurrentWorkspace(personaId, "update", agent);
+    log(stepLine(3, UPDATE_TOTAL_STEPS, "Backing up current version", "OK"));
+
+    // [4/5] Install new files
+    log(stepLine(4, UPDATE_TOTAL_STEPS, "Installing updated files", ""));
+    const installedFiles: string[] = [];
+    for (const f of [...REQUIRED_FILES, ...OPTIONAL_FILES]) {
+      const src = join(packagePath, f);
+      if (await exists(src)) {
+        await cp(src, join(workspace, f), { force: true });
+        installedFiles.push(f);
+      }
+    }
+
+    const skillsSrc = join(packagePath, "skills");
+    if (await exists(skillsSrc)) {
+      const skillsDest = join(workspace, "skills");
+      await mkdir(skillsDest, { recursive: true });
+      const entries = await readdir(skillsSrc, { withFileTypes: true });
+      for (const entry of entries) {
+        const srcPath = join(skillsSrc, entry.name);
+        const destPath = join(skillsDest, entry.name);
+        if (entry.isDirectory()) {
+          await cp(srcPath, destPath, { recursive: true, force: true });
+          installedFiles.push(`skills/${entry.name}/`);
+        } else {
+          await cp(srcPath, destPath, { force: true });
+          installedFiles.push(`skills/${entry.name}`);
+        }
+      }
+    }
+    log(stepLine(4, UPDATE_TOTAL_STEPS, "Installing updated files", `OK (${installedFiles.length} files)`));
+
+    // [5/5] Update registry
+    log(stepLine(5, UPDATE_TOTAL_STEPS, "Updating registry", ""));
+    await updateAgentRecord(personaId, {
+      version: manifest.version,
+      updated_at: new Date().toISOString(),
+      source: packagePath,
+      backup_path: backupPath,
+      files: installedFiles,
+      skills: [...newSkills],
+    }, agent);
+    log(stepLine(5, UPDATE_TOTAL_STEPS, "Updating registry", "OK"));
+
+    log(`\n  Updated: ${manifest.name} ${current.version} -> ${manifest.version}`);
+    log(`  Backup of previous version: ${backupPath}`);
+    log(`\n  Next: restart your OpenClaw session to load the updated persona\n`);
+
+    return { state: "success" };
+  } catch (err) {
+    return { state: "failed", error: (err as Error).message };
+  }
+}

package/src/core/packager.ts

@@ -0,0 +1,229 @@
+import { readFile, readdir, access, writeFile, stat, mkdir } from "node:fs/promises";
+import { join, basename } from "node:path";
+import {
+  MANIFEST_FILE,
+  REQUIRED_FILES,
+  OPTIONAL_FILES,
+  PACK_TOTAL_STEPS,
+  PLUGIN_VERSION,
+} from "../constants.js";
+import type { AgentManifest, SkillDependency } from "../types.js";
+import { resolveWorkspace } from "./workspace.js";
+import { createZip } from "../utils/zip.js";
+import { computeSha256 } from "../utils/checksum.js";
+import { stepLine } from "../utils/output.js";
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Skill detection ────────────────────────────────────────────────
+
+interface DetectedSkill {
+  id: string;
+  confidence: "high" | "low";
+  source: string;
+}
+
+/**
+ * Detect skills from the package directory or current workspace.
+ *
+ * High confidence: skills listed in agent.json, or present in skills/ directory.
+ * Low confidence: skill-like references in AGENTS.md / SOUL.md.
+ */
+async function detectSkills(packagePath: string): Promise<DetectedSkill[]> {
+  const detected: DetectedSkill[] = [];
+  const seen = new Set<string>();
+
+  // From agent.json
+  const manifestPath = join(packagePath, MANIFEST_FILE);
+  if (await exists(manifestPath)) {
+    try {
+      const manifest: AgentManifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+      for (const s of manifest.skills ?? []) {
+        if (!seen.has(s.id)) {
+          detected.push({ id: s.id, confidence: "high", source: "agent.json" });
+          seen.add(s.id);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // From skills/ directory
+  const skillsDir = join(packagePath, "skills");
+  if (await exists(skillsDir)) {
+    const entries = await readdir(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const skillId = entry.name.replace(/\.md$/i, "");
+      if (!seen.has(skillId)) {
+        detected.push({ id: skillId, confidence: "high", source: "skills/ directory" });
+        seen.add(skillId);
+      }
+    }
+  }
+
+  // Heuristic: scan AGENTS.md / SOUL.md for skill-like references
+  for (const mdFile of ["AGENTS.md", "SOUL.md"]) {
+    const fp = join(packagePath, mdFile);
+    if (await exists(fp)) {
+      const content = await readFile(fp, "utf-8");
+      const skillRefs = content.match(/(?:skill|能力|技能)[：:]\s*([a-z0-9-]+)/gi);
+      if (skillRefs) {
+        for (const ref of skillRefs) {
+          const match = ref.match(/([a-z0-9-]+)$/i);
+          if (match && !seen.has(match[1])) {
+            detected.push({ id: match[1], confidence: "low", source: mdFile });
+            seen.add(match[1]);
+          }
+        }
+      }
+    }
+  }
+
+  return detected;
+}
+
+// ─── Pack from directory ────────────────────────────────────────────
+
+export interface PackOptions {
+  packagePath: string;
+  outputDir?: string;
+  name?: string;
+  category?: string;
+  log: (msg: string) => void;
+}
+
+export async function packAgent(opts: PackOptions): Promise<{
+  zipPath: string;
+  sizeKb: number;
+  manifest: AgentManifest;
+} | null> {
+  const { packagePath, log } = opts;
+
+  // [1/3] Validate
+  log(stepLine(1, PACK_TOTAL_STEPS, "Validating package", ""));
+  let manifest: AgentManifest;
+  const manifestPath = join(packagePath, MANIFEST_FILE);
+  if (await exists(manifestPath)) {
+    manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+  } else {
+    log(`  No ${MANIFEST_FILE} found. Generating from directory contents...`);
+    const dirName = basename(packagePath);
+    manifest = {
+      id: dirName.toLowerCase().replace(/[^a-z0-9-]/g, "-"),
+      slug: dirName.toLowerCase().replace(/[^a-z0-9-]/g, "-"),
+      name: opts.name ?? dirName,
+      subtitle: "",
+      description: "",
+      version: "1.0.0",
+      author: "",
+      license: "Commercial",
+      price: 0,
+      currency: "USD",
+      category: opts.category ?? "general",
+      tags: [],
+      openclaw_version: ">=0.8.0",
+      entry_files: [],
+      skills: [],
+    };
+  }
+
+  // Validate required files
+  const missingRequired: string[] = [];
+  for (const f of REQUIRED_FILES) {
+    if (!(await exists(join(packagePath, f)))) {
+      missingRequired.push(f);
+    }
+  }
+  if (missingRequired.length > 0) {
+    log(stepLine(1, PACK_TOTAL_STEPS, "Validating package", "FAILED"));
+    for (const f of missingRequired) log(`    - Missing: ${f}`);
+    return null;
+  }
+  log(stepLine(1, PACK_TOTAL_STEPS, "Validating package", "OK"));
+
+  // [2/3] Detect skills and compute checksums
+  log(stepLine(2, PACK_TOTAL_STEPS, "Detecting skills & checksums", ""));
+  const detectedSkills = await detectSkills(packagePath);
+  const highConfidence = detectedSkills.filter((s) => s.confidence === "high");
+  const lowConfidence = detectedSkills.filter((s) => s.confidence === "low");
+
+  if (highConfidence.length > 0) {
+    log(`  Detected Skills: ${highConfidence.map((s) => s.id).join(", ")}`);
+  }
+  if (lowConfidence.length > 0) {
+    log(`  Suggested Skills: ${lowConfidence.map((s) => s.id).join(", ")}`);
+  }
+
+  // Update manifest skills from detection if empty
+  if (manifest.skills.length === 0 && highConfidence.length > 0) {
+    manifest.skills = highConfidence.map((s) => ({
+      id: s.id,
+      version: "^1.0.0",
+      required: true,
+    }));
+  }
+
+  // Update entry_files from actual files
+  const actualEntryFiles: string[] = [];
+  for (const f of [...REQUIRED_FILES, ...OPTIONAL_FILES]) {
+    if (await exists(join(packagePath, f))) {
+      actualEntryFiles.push(f);
+    }
+  }
+  manifest.entry_files = actualEntryFiles;
+
+  // Set pack metadata
+  manifest.packed_at = new Date().toISOString();
+  manifest.packaged_by = `clawstore-plugin@${PLUGIN_VERSION}`;
+
+  // Compute checksum for SOUL.md
+  const soulPath = join(packagePath, "SOUL.md");
+  if (await exists(soulPath)) {
+    manifest.checksum = await computeSha256(soulPath);
+  }
+
+  // Write updated manifest back
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+  log(stepLine(2, PACK_TOTAL_STEPS, "Detecting skills & checksums", "OK"));
+
+  // [3/3] Create ZIP
+  const outputDir = opts.outputDir ?? join(packagePath, "..");
+  await mkdir(outputDir, { recursive: true });
+  const zipName = `${manifest.id}-v${manifest.version}.zip`;
+  const zipPath = join(outputDir, zipName);
+
+  log(stepLine(3, PACK_TOTAL_STEPS, `Creating ZIP: ${zipName}`, ""));
+  const result = await createZip(packagePath, zipPath);
+  const sizeKb = result.sizeBytes / 1024;
+  log(stepLine(3, PACK_TOTAL_STEPS, `Creating ZIP: ${zipName}`, "OK"));
+
+  log(`\n  Package: ${zipPath}`);
+  log(`  Size:    ${sizeKb.toFixed(1)} KB`);
+  log(`\n  Ready to upload to Clawstore or distribute as ZIP.\n`);
+
+  return { zipPath, sizeKb, manifest };
+}
+
+// ─── Pack from current workspace ────────────────────────────────────
+
+export async function packCurrentAgent(opts: {
+  name?: string;
+  category?: string;
+  outputDir?: string;
+  log: (msg: string) => void;
+}): Promise<ReturnType<typeof packAgent>> {
+  const workspace = await resolveWorkspace();
+  return packAgent({
+    packagePath: workspace,
+    outputDir: opts.outputDir,
+    name: opts.name,
+    category: opts.category,
+    log: opts.log,
+  });
+}