mnemospark 0.1.2

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "mnemospark",
+  "version": "0.1.2",
+  "description": "mnemospark is a OpenClaw plugin that enables cloud services workflows with wallet management and x402 USDC payments on Base.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mnemospark": "./dist/cli.js"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test:install-check": "node test/install-check.mjs",
+    "prepare": "node scripts/sync-plugin-version.js && husky"
+  },
+  "keywords": [
+    "openclaw",
+    "mnemospark",
+    "storage",
+    "wallet",
+    "x402",
+    "usdc",
+    "base",
+    "payment",
+    "cloud-storage",
+    "plugin",
+    "agentic-commerce"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:pawlsclick/mnemospark.git"
+  },
+  "homepage": "https://github.com/pawlsclick/mnemospark#readme",
+  "bugs": {
+    "url": "https://github.com/pawlsclick/mnemospark/issues"
+  },
+  "dependencies": {
+    "viem": "^2.39.3"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2025.1.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,mjs,json,md}": "prettier --write",
+    "src/**/*.{ts,tsx}": "eslint --fix"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "openclaw": "latest",
+    "prettier": "^3.8.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/README.md

@@ -0,0 +1,61 @@
+# Scripts
+
+Development and install scripts for mnemospark.
+
+## Install scripts (run once per machine)
+
+**Prerequisites:** Node.js v20+ is required for pnpm. AWS credentials and GitHub auth are configured separately (IAM role, `aws configure`, `gh auth login`).
+
+| Script                         | Purpose                                          |
+| ------------------------------ | ------------------------------------------------ |
+| `./scripts/install-pnpm.sh`    | Enable pnpm via Node corepack. Idempotent.       |
+| `./scripts/install-aws-cli.sh` | Install AWS CLI v2 on Ubuntu x86_64. Idempotent. |
+| `./scripts/install-jq.sh`      | Optional: install jq via apt. Idempotent.        |
+
+Run from repo root, e.g.:
+
+```bash
+./scripts/install-pnpm.sh
+./scripts/install-aws-cli.sh
+```
+
+AWS CLI credentials are not installed by the script; use IAM role or `aws configure` per environment.
+
+## Verification
+
+```bash
+./scripts/verify-dev-tools.sh
+```
+
+Checks: `aws --version`, `aws sts get-caller-identity`, `node -v`, `pnpm -v`, `git --version`, `gh auth status`. Optionally runs `pnpm install`, `pnpm build`, `pnpm test` unless `SKIP_PNPM_BUILD=1`.
+
+Full pass requires AWS credentials and `gh auth login` to be configured.
+
+## Optional: jq
+
+jq is optional (per development_tools_requirements_doc). To install on Ubuntu:
+
+```bash
+sudo apt install -y jq
+```
+
+Or run `./scripts/install-jq.sh` if present.
+
+## Documentation (`.company`)
+
+Documentation lives in the **mnemospark-docs** Git submodule at `.company`. After cloning this repo, run `git submodule update --init` to populate `.company` (or clone with `git clone --recurse-submodules`). Do not edit `.company` here; edit in the [mnemospark-docs](https://github.com/pawlsclick/mnemospark-docs) repo, then update the submodule pointer in this repo.
+
+## Seed mnemospark-backend (examples and legacy)
+
+Before running Cursor Cloud Agent on backend features (01–10, 15–18), you may seed **mnemospark-backend** with examples from this repo (docs are now provided via the mnemospark-docs submodule in both repos):
+
+```bash
+./scripts/seed-mnemospark-backend.sh /path/to/mnemospark-backend
+```
+
+Then open mnemospark-backend in Cursor and start the Cloud Agent there. See [.company/features_cursor_dev/README.md](../.company/features_cursor_dev/README.md) for where to run each feature.
+
+## Other scripts
+
+- `reinstall.sh` — Reinstall mnemospark OpenClaw plugin.
+- `uninstall.sh` — Uninstall mnemospark plugin and clean config.

package/scripts/install-aws-cli.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Install AWS CLI v2 on Ubuntu (x86_64). Idempotent: if aws --version already shows v2.x, exit 0.
+# Credentials are out of scope (IAM role or aws configure per environment).
+set -e
+
+AWS_URL="https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip"
+TMP_DIR="${TMPDIR:-/tmp}/awscliv2-$$"
+
+if command -v aws >/dev/null 2>&1; then
+  ver=$(aws --version 2>&1 || true)
+  if [[ "$ver" =~ aws-cli/2\. ]]; then
+    echo "AWS CLI v2 already installed: $ver"
+    exit 0
+  fi
+fi
+
+cleanup() { rm -rf "$TMP_DIR"; }
+trap cleanup EXIT
+mkdir -p "$TMP_DIR"
+cd "$TMP_DIR"
+
+echo "Downloading AWS CLI v2..."
+curl -sSfL "$AWS_URL" -o awscliv2.zip
+unzip -q awscliv2.zip
+sudo ./aws/install -i /usr/local/aws-cli -b /usr/local/bin
+
+echo "AWS CLI v2 installed: $(aws --version)"
+exit 0

package/scripts/install-jq.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Optional: install jq on Ubuntu. Idempotent: if jq already works, exit 0.
+# See development_tools_requirements_doc.md §2.7 — jq is optional.
+set -e
+
+if command -v jq >/dev/null 2>&1; then
+  jq --version >/dev/null 2>&1 && { echo "jq already installed: $(jq --version)"; exit 0; }
+fi
+
+sudo apt-get update -qq
+sudo apt-get install -y jq
+echo "jq installed: $(jq --version)"
+exit 0

package/scripts/install-pnpm.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Install and enable pnpm on Ubuntu dev instance via Node corepack.
+# Idempotent: if pnpm already works, exit 0.
+# Prerequisite: Node.js v20+ (engines in package.json).
+set -e
+
+if command -v pnpm >/dev/null 2>&1; then
+  pnpm -v >/dev/null 2>&1 && { echo "pnpm already installed: $(pnpm -v)"; exit 0; }
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "Error: Node.js is required. Install Node.js v20+ first." >&2
+  exit 1
+fi
+
+corepack enable
+corepack prepare pnpm@latest --activate
+
+echo "pnpm installed: $(pnpm -v)"
+exit 0

package/scripts/reinstall.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "mnemospark reinstall"
+echo ""
+
+# 1. Remove mnemospark plugin files only
+echo "→ Removing plugin files..."
+rm -rf ~/.openclaw/extensions/mnemospark
+
+# 2. Clean only mnemospark config entries (do not touch blockrun/openclaw)
+echo "→ Cleaning config entries (mnemospark only)..."
+node -e "
+const f = require('os').homedir() + '/.openclaw/openclaw.json';
+const fs = require('fs');
+if (!fs.existsSync(f)) {
+  console.log('  No openclaw.json found, skipping');
+  process.exit(0);
+}
+
+let c;
+try {
+  c = JSON.parse(fs.readFileSync(f, 'utf8'));
+} catch (err) {
+  const backupPath = f + '.corrupt.' + Date.now();
+  console.error('  ERROR: Invalid JSON in openclaw.json');
+  console.error('  ' + err.message);
+  try {
+    fs.copyFileSync(f, backupPath);
+    console.log('  Backed up to: ' + backupPath);
+  } catch {}
+  console.log('  Skipping config cleanup...');
+  process.exit(0);
+}
+
+if (c.plugins?.entries?.mnemospark) delete c.plugins.entries.mnemospark;
+if (c.plugins?.installs?.mnemospark) delete c.plugins.installs.mnemospark;
+if (Array.isArray(c.plugins?.allow)) {
+  c.plugins.allow = c.plugins.allow.filter(p => p !== 'mnemospark');
+}
+fs.writeFileSync(f, JSON.stringify(c, null, 2));
+console.log('  Config cleaned');
+"
+
+# 3. Kill mnemospark proxy (port 7120)
+echo "→ Stopping old proxy..."
+lsof -ti :7120 | xargs kill -9 2>/dev/null || true
+
+# 4. Remove stale models cache so it gets regenerated
+echo "→ Cleaning models cache..."
+rm -f ~/.openclaw/agents/main/agent/models.json 2>/dev/null || true
+
+# 5. Install mnemospark plugin
+echo "→ Installing mnemospark..."
+openclaw plugins install mnemospark
+
+# 6. Verify installation
+echo "→ Verifying installation..."
+DIST_PATH="$HOME/.openclaw/extensions/mnemospark/dist/index.js"
+if [ ! -f "$DIST_PATH" ]; then
+  echo "  ⚠️  dist/ files missing, clearing npm cache and retrying..."
+  npm cache clean --force 2>/dev/null || true
+  rm -rf ~/.openclaw/extensions/mnemospark
+  openclaw plugins install mnemospark
+
+  if [ ! -f "$DIST_PATH" ]; then
+    echo "  ❌ Installation failed - dist/index.js still missing"
+    exit 1
+  fi
+fi
+echo "  ✓ dist/index.js verified"
+
+# 7. Ensure mnemospark is in plugins.allow
+echo "→ Adding to plugins allow list..."
+node -e "
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const configPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+
+if (fs.existsSync(configPath)) {
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (!config.plugins) config.plugins = {};
+    if (!Array.isArray(config.plugins.allow)) config.plugins.allow = [];
+    if (!config.plugins.allow.includes('mnemospark')) {
+      config.plugins.allow.push('mnemospark');
+      console.log('  Added mnemospark to plugins.allow');
+    }
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  } catch (e) {
+    console.log('  Could not update config:', e.message);
+  }
+}
+"
+
+echo ""
+echo "✓ Done. Run: openclaw gateway restart"
+echo ""
+echo "To uninstall: bash ~/.openclaw/extensions/mnemospark/scripts/uninstall.sh"

package/scripts/seed-mnemospark-backend.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Seed mnemospark-backend with examples and .company docs required by backend feature specs (01-10, 15-17).
+# Usage: from mnemospark repo root: ./scripts/seed-mnemospark-backend.sh /path/to/mnemospark-backend
+# Idempotent: safe to run again; overwrites existing files.
+
+set -e
+
+if [ -z "$1" ]; then
+  echo "Usage: $0 /path/to/mnemospark-backend" >&2
+  exit 1
+fi
+
+DEST="$1"
+# Resolve repo root: script lives in mnemospark/scripts/
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+if [ ! -d "$ROOT/.company" ] || [ ! -d "$ROOT/examples" ]; then
+  echo "Error: must run from mnemospark repo (missing .company or examples). Root: $ROOT" >&2
+  exit 1
+fi
+
+mkdir -p "$DEST"
+echo "Seeding mnemospark-backend at $DEST from $ROOT"
+
+# --- Examples (exclude .aws-sam build output) ---
+copy_example_dir() {
+  local src="$1"
+  local name="$2"
+  shift 2
+  local files=("$@")
+  mkdir -p "$DEST/examples/$name"
+  for f in "${files[@]}"; do
+    if [ -f "$ROOT/$src/$f" ]; then
+      cp "$ROOT/$src/$f" "$DEST/examples/$name/"
+    fi
+  done
+}
+
+copy_example_dir "examples/s3-cost-estimate-api" "s3-cost-estimate-api" \
+  app.py template.yaml requirements.txt README.md samconfig.toml
+
+copy_example_dir "examples/data-transfer-cost-estimate-api" "data-transfer-cost-estimate-api" \
+  app.py template.yaml requirements.txt README.md samconfig.toml
+
+mkdir -p "$DEST/examples"
+if [ -f "$ROOT/examples/object_storage_management_aws.py" ]; then
+  cp "$ROOT/examples/object_storage_management_aws.py" "$DEST/examples/"
+fi
+
+copy_example_dir "examples/object-storage-management-api" "object-storage-management-api" \
+  app.py template.yaml requirements.txt storage_core.py README.md
+
+# --- .company ---
+mkdir -p "$DEST/.company"
+mkdir -p "$DEST/.company/infrastructure_design"
+mkdir -p "$DEST/.company/features_cursor_dev"
+
+for f in \
+  mnemospark_backend_api_spec.md \
+  mnemospark_full_workflow.md \
+  mnemospark_PRD.md \
+  clawrouter_wallet_gen_payment_eip712.md \
+; do
+  if [ -f "$ROOT/.company/$f" ]; then
+    cp "$ROOT/.company/$f" "$DEST/.company/"
+  fi
+done
+
+if [ -f "$ROOT/.company/infrastructure_design/internet_facing_API.md" ]; then
+  cp "$ROOT/.company/infrastructure_design/internet_facing_API.md" "$DEST/.company/infrastructure_design/"
+fi
+
+for f in \
+  AWS_DOCS_REFERENCES.md \
+  README.md \
+  cursor-dev-01-lambda-estimate-storage.md \
+  cursor-dev-02-lambda-estimate-transfer.md \
+  cursor-dev-03-lambda-price-storage.md \
+  cursor-dev-04-lambda-storage-upload.md \
+  cursor-dev-05-lambda-storage-ls.md \
+  cursor-dev-06-lambda-storage-download.md \
+  cursor-dev-07-lambda-storage-delete.md \
+  cursor-dev-08-api-gateway-auth.md \
+  cursor-dev-09-dynamodb-tables.md \
+  cursor-dev-10-housekeeping-32day.md \
+  cursor-dev-15-cfn-waf.md \
+  cursor-dev-16-cfn-observability.md \
+  cursor-dev-17-cfn-cloudfront.md \
+; do
+  if [ -f "$ROOT/.company/features_cursor_dev/$f" ]; then
+    cp "$ROOT/.company/features_cursor_dev/$f" "$DEST/.company/features_cursor_dev/"
+  fi
+done
+
+echo "Done. Backend repo seeded at $DEST"

package/scripts/sync-plugin-version.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * Sync openclaw.plugin.json "version" from package.json.
+ * Run from repo root: node scripts/sync-plugin-version.js
+ * Used in prepare script so version cannot drift.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, "..");
+const pkgPath = join(root, "package.json");
+const pluginPath = join(root, "openclaw.plugin.json");
+
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+const plugin = JSON.parse(readFileSync(pluginPath, "utf8"));
+
+// Keep plugin metadata in sync with package.json for version and description.
+plugin.version = pkg.version;
+plugin.description = pkg.description;
+
+writeFileSync(pluginPath, JSON.stringify(plugin, null, 2) + "\n", "utf8");

package/scripts/uninstall.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -e
+
+echo "mnemospark uninstall"
+echo ""
+
+# 1. Stop mnemospark proxy (port 7120)
+echo "→ Stopping proxy..."
+lsof -ti :7120 | xargs kill -9 2>/dev/null || true
+
+# 2. Remove mnemospark plugin files only
+echo "→ Removing plugin files..."
+rm -rf ~/.openclaw/extensions/mnemospark
+
+# 3. Clean only mnemospark entries from openclaw.json (do not touch blockrun/openclaw)
+echo "→ Cleaning openclaw.json (mnemospark only)..."
+node -e "
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const configPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+
+if (!fs.existsSync(configPath)) {
+  console.log('  No openclaw.json found, skipping');
+  process.exit(0);
+}
+
+try {
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  let changed = false;
+
+  // Remove only mnemospark plugin entries
+  if (config.plugins?.entries?.mnemospark) {
+    delete config.plugins.entries.mnemospark;
+    changed = true;
+  }
+  if (config.plugins?.installs?.mnemospark) {
+    delete config.plugins.installs.mnemospark;
+    changed = true;
+  }
+
+  // Remove only mnemospark from plugins.allow
+  if (Array.isArray(config.plugins?.allow)) {
+    const before = config.plugins.allow.length;
+    config.plugins.allow = config.plugins.allow.filter(p => p !== 'mnemospark');
+    if (config.plugins.allow.length !== before) {
+      console.log('  Removed mnemospark from plugins.allow');
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    console.log('  Config cleaned');
+  } else {
+    console.log('  No mnemospark entries found');
+  }
+} catch (err) {
+  console.error('  Error:', err.message);
+}
+"
+
+echo ""
+echo "✓ mnemospark uninstalled"
+echo ""
+echo "Restart OpenClaw to apply changes:"
+echo "  openclaw gateway restart"

package/scripts/verify-dev-tools.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Verify required development tools for mnemospark. Exit 0 only if all checks pass.
+# Run from repo root. AWS credentials and gh auth must be configured for full pass.
+# Optional: set SKIP_PNPM_BUILD=1 to skip pnpm install/build/test (e.g. when no AWS creds).
+set -e
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+fail() { echo "  FAIL: $1" >&2; exit 1; }
+
+echo "Checking aws..."
+command -v aws >/dev/null 2>&1 || fail "aws not found. Run scripts/install-aws-cli.sh"
+aws --version >/dev/null 2>&1 || fail "aws --version failed"
+echo "  ok"
+
+echo "Checking aws sts get-caller-identity..."
+aws sts get-caller-identity >/dev/null 2>&1 || fail "AWS credentials not configured (aws sts get-caller-identity failed). Use IAM role or aws configure."
+echo "  ok"
+
+echo "Checking node..."
+command -v node >/dev/null 2>&1 || fail "node not found. Install Node.js v20+."
+node -v >/dev/null 2>&1 || fail "node -v failed"
+echo "  ok"
+
+echo "Checking pnpm..."
+command -v pnpm >/dev/null 2>&1 || fail "pnpm not found. Run scripts/install-pnpm.sh"
+pnpm -v >/dev/null 2>&1 || fail "pnpm -v failed"
+echo "  ok"
+
+echo "Checking git..."
+command -v git >/dev/null 2>&1 || fail "git not found"
+git --version >/dev/null 2>&1 || fail "git --version failed"
+echo "  ok"
+
+echo "Checking gh auth status..."
+command -v gh >/dev/null 2>&1 || fail "gh (GitHub CLI) not found"
+# Use --json so exit code is 0 when logged in (avoids exit 1 from "plain text" warning)
+gh auth status --json hosts >/dev/null 2>&1 || fail "gh auth status failed. Run gh auth login."
+echo "  ok"
+
+if [[ "${SKIP_PNPM_BUILD}" == "1" ]]; then
+  echo "Skipping pnpm install/build/test (SKIP_PNPM_BUILD=1)"
+else
+  echo "Running pnpm install..."
+  pnpm install || fail "pnpm install failed"
+  echo "  ok"
+  echo "Running pnpm build..."
+  pnpm build || fail "pnpm build failed"
+  echo "  ok"
+  echo "Running pnpm test..."
+  pnpm test || fail "pnpm test failed"
+  echo "  ok"
+fi
+
+echo "All required dev tools verified."