@twelvehart/supermemory-runtime 1.0.0-next.0 → 1.0.0-next.2

package/Dockerfile

@@ -0,0 +1,120 @@
+# =============================================================================
+# SuperMemory Clone API - Multi-stage Dockerfile
+# =============================================================================
+# This Dockerfile uses a multi-stage build for optimal image size:
+# - Stage 1 (deps): Install all dependencies
+# - Stage 2 (builder): Build TypeScript to JavaScript
+# - Stage 3 (runner): Production runtime with minimal footprint
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Stage 1: Dependencies
+# -----------------------------------------------------------------------------
+# Install all dependencies including devDependencies for building
+FROM node:20-alpine AS deps
+
+# Install build dependencies required for native modules (better-sqlite3)
+# - python3 and make are needed for node-gyp
+# - g++ is the C++ compiler
+# - libc6-compat ensures glibc compatibility
+RUN apk add --no-cache python3 make g++ libc6-compat
+
+WORKDIR /app
+
+# Copy package files for dependency installation
+# This layer is cached unless package*.json changes
+COPY package.json package-lock.json ./
+
+# Install all dependencies (including dev for TypeScript compilation)
+# Use --legacy-peer-deps if you encounter peer dependency issues
+RUN npm ci
+
+# -----------------------------------------------------------------------------
+# Stage 2: Builder
+# -----------------------------------------------------------------------------
+# Compile TypeScript to JavaScript
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy dependencies from deps stage
+COPY --from=deps /app/node_modules ./node_modules
+
+# Copy source code and configuration files
+COPY package.json package-lock.json tsconfig.json ./
+COPY src ./src
+COPY drizzle.config.ts ./
+
+# Build TypeScript
+RUN npm run build
+
+# Generate drizzle migrations if schema exists
+# This ensures migrations are available in production
+RUN npm run db:generate || true
+
+# Prune dev dependencies for production
+# This removes TypeScript, test frameworks, etc.
+RUN npm prune --production
+
+# -----------------------------------------------------------------------------
+# Stage 3: Production Runner
+# -----------------------------------------------------------------------------
+# Minimal production image
+FROM node:20-alpine AS runner
+
+# Add labels for container metadata
+LABEL org.opencontainers.image.title="SuperMemory Clone API"
+LABEL org.opencontainers.image.description="Personal AI memory assistant with semantic search"
+LABEL org.opencontainers.image.version="1.0.0"
+LABEL org.opencontainers.image.vendor="SuperMemory Clone"
+
+# Install runtime dependencies only
+# - libc6-compat: Required for better-sqlite3 native bindings
+# - tini: Proper init system for signal handling in containers
+RUN apk add --no-cache libc6-compat tini
+
+# Create non-root user for security
+# Running as root in containers is a security risk
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 supermemory
+
+WORKDIR /app
+
+# Create data directory for SQLite database
+# This directory should be mounted as a volume in production
+RUN mkdir -p /app/data && chown -R supermemory:nodejs /app/data
+
+# Copy production files from builder
+COPY --from=builder --chown=supermemory:nodejs /app/node_modules ./node_modules
+COPY --from=builder --chown=supermemory:nodejs /app/dist ./dist
+COPY --from=builder --chown=supermemory:nodejs /app/package.json ./
+COPY --from=builder --chown=supermemory:nodejs /app/drizzle ./drizzle
+
+# Copy entrypoint script
+COPY --chown=supermemory:nodejs scripts/docker-entrypoint.sh /app/docker-entrypoint.sh
+RUN chmod +x /app/docker-entrypoint.sh
+
+# Switch to non-root user
+USER supermemory
+
+# Set environment variables
+# NODE_ENV=production enables production optimizations
+ENV NODE_ENV=production
+ENV API_HOST=0.0.0.0
+ENV API_PORT=3000
+
+# Expose API port
+EXPOSE 3000
+
+# Health check to verify the container is running properly
+# Checks the /health endpoint every 30 seconds
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+# Use tini as init system for proper signal handling
+# This ensures SIGTERM is properly forwarded to Node.js
+ENTRYPOINT ["/sbin/tini", "--"]
+
+# Run with node directly (not npm) for proper signal handling
+# npm doesn't forward signals properly to child processes
+CMD ["/app/docker-entrypoint.sh"]

package/README.md

@@ -33,12 +33,12 @@ It stores documents, extracts memories, indexes embeddings, and serves search/pr
 Primary path for first-time users:
 
 ```bash
-npx -y @twelvehart/supermemory@latest full --dir ./supermemory --mcp project
-cd ./supermemory
+npx -y @twelvehart/supermemory@latest full --mcp project
+cd ~/.supermemory
 claude
 ```
 
-That command unpacks the runtime into `./supermemory`, runs the canonical `scripts/install.sh` from the final directory, registers Claude MCP against that final path, and prints only the next steps a new user can actually take.
+That command unpacks the runtime into `~/.supermemory`, runs the canonical `scripts/install.sh` from the final directory, registers Claude MCP against that final path, and prints only the next steps a new user can actually take.
 
 The npx installer supports:
 
@@ -331,6 +331,38 @@ claude mcp get supermemory
 - `npm run pack:check:runtime` - Verify the runtime npm tarball contents
 - `npm run validate` - typecheck + lint + format + tests
 
+## Claude Sandbox VM
+
+For isolated Claude Code and plugin testing on macOS/Linux hosts, use Multipass with the bundled sandbox scripts.
+
+Host prerequisite: install Multipass on the host. On macOS, for example:
+
+```bash
+brew install --cask multipass
+```
+
+Create and provision a reusable Ubuntu VM with Docker, Node/npm, uv, Claude Code, and common CLI tools:
+
+```bash
+./scripts/claude-sandbox-vm.sh create --mount "$PWD:/home/ubuntu/workspace/repo"
+```
+
+Common operations:
+
+```bash
+./scripts/claude-sandbox-vm.sh info
+./scripts/claude-sandbox-vm.sh shell
+./scripts/claude-sandbox-vm.sh exec -- claude --version
+./scripts/claude-sandbox-vm.sh provision
+./scripts/claude-sandbox-vm.sh delete
+```
+
+Notes:
+
+- The VM installs Claude Code from npm but does not authenticate it for you; run `claude login` inside the VM.
+- Docker group membership is added during provisioning; reconnect or run `exec newgrp docker` before using Docker.
+- Override defaults with env vars such as `CLAUDE_SANDBOX_VM_NAME`, `CLAUDE_SANDBOX_MEMORY`, `NODE_MAJOR`, and `CLAUDE_NPM_PACKAGE`.
+
 ## Testing
 
 - Unit/integration tests: `vitest`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twelvehart/supermemory-runtime",
-  "version": "1.0.0-next.0",
+  "version": "1.0.0-next.2",
   "description": "A personal AI memory assistant - supermemory.ai clone",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,6 +8,7 @@
   "files": [
     "README.md",
     ".env.example",
+    "Dockerfile",
     "package-lock.json",
     "src",
     "scripts",

package/scripts/check-runtime-pack.ts

@@ -14,6 +14,7 @@ interface PackResult {
 
 const REQUIRED_PATHS = [
   '.env.example',
+  'Dockerfile',
   'docker-compose.prod.yml',
   'docker-compose.yml',
   'package.json',
@@ -30,7 +31,6 @@ const REQUIRED_PATHS = [
 const FORBIDDEN_PATTERNS = [
   /^coverage\//,
   /^data\//,
-  /^dist\//,
   /^packages\//,
   /^tests\//,
   /^2026-03-05-npx-first-installer-/,