clawpad 0.3.0 → 0.3.2

package/bin/clawpad.js

@@ -16,6 +16,12 @@ const FORCE_KILL_GRACE_MS = 1500;
 const FORCE_KILL_VERIFY_MS = 4000;
 const SHUTDOWN_GRACE_MS = 5000;
 const PORT_RELEASE_TIMEOUT_MS = 4000;
+const CRASH_RESTART_WINDOW_MS = 60_000;
+const MAX_CRASH_RESTARTS = 3;
+const CRASH_LOG_DIR = path.join(os.homedir(), ".clawpad", "logs");
+const CRASH_LOG_PATH = path.join(CRASH_LOG_DIR, "launcher-crashes.log");
+const QMD_INSTALL_SCRIPT_URL =
+  "https://raw.githubusercontent.com/tobi/qmd/main/install.sh";
 
 // ─── Arg Parsing ─────────────────────────────────────────
 const args = process.argv.slice(2);
@@ -33,6 +39,7 @@ let port =
 const portExplicit = portIdx !== -1 || Boolean(process.env.PORT);
 
 const shouldOpen = !args.includes("--no-open");
+const shouldSetup = args.includes("--setup");
 const shouldIntegrate = !args.includes("--no-integrate");
 const autoYes = args.includes("--yes");
 const noPrompt = args.includes("--no-prompt");
@@ -68,6 +75,7 @@ function printHelp() {
     --no-open           Don't auto-open the browser
     --pages-dir <dir>   Override docs directory (default: auto)
     --migrate[=mode]    Migrate legacy docs (mode: move|copy)
+    --setup             Open setup onboarding flow on launch
     --no-integrate      Skip OpenClaw integration prompt
     --yes               Auto-approve integration steps
     --no-prompt         Disable integration prompt (skip changes)
@@ -78,6 +86,7 @@ function printHelp() {
     clawpad                 Start on port ${DEFAULT_PORT}
     clawpad -p 4000         Start on port 4000
     clawpad --no-open       Start without opening browser
+    clawpad --setup         Start and open setup onboarding
     clawpad --yes           Auto-integrate with OpenClaw if detected
 `);
 }
@@ -152,6 +161,83 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function appendCrashLog(lines) {
+  try {
+    if (!fs.existsSync(CRASH_LOG_DIR)) {
+      fs.mkdirSync(CRASH_LOG_DIR, { recursive: true });
+    }
+    const payload = `${lines.join("\n")}\n\n`;
+    fs.appendFileSync(CRASH_LOG_PATH, payload, "utf-8");
+  } catch {
+    // best effort
+  }
+}
+
+function safeCommandOutput(cmd) {
+  try {
+    return execSync(cmd, { stdio: ["ignore", "pipe", "ignore"] })
+      .toString()
+      .trim();
+  } catch {
+    return "(unavailable)";
+  }
+}
+
+function collectKillHints() {
+  const hints = [];
+
+  if (process.platform === "darwin") {
+    hints.push("macOS log hints (last 2m):");
+    hints.push(
+      safeCommandOutput(
+        `log show --style compact --last 2m --predicate '(eventMessage CONTAINS[c] "kill" OR eventMessage CONTAINS[c] "killed") AND (eventMessage CONTAINS[c] "node" OR eventMessage CONTAINS[c] "clawpad")' | tail -n 30`,
+      ),
+    );
+    return hints;
+  }
+
+  if (process.platform === "linux") {
+    hints.push("kernel hints:");
+    hints.push(safeCommandOutput("dmesg | tail -n 30"));
+    return hints;
+  }
+
+  return hints;
+}
+
+function recordCrashDiagnostics({ signal, code, childPid, runningPort, startAt }) {
+  const now = Date.now();
+  const reason = signal ? `signal ${signal}` : `exit code ${code}`;
+  const lines = [
+    `[${new Date(now).toISOString()}] ClawPad child terminated unexpectedly`,
+    `reason=${reason}`,
+    `launcherPid=${process.pid}`,
+    `launcherPpid=${process.ppid}`,
+    `childPid=${childPid ?? "unknown"}`,
+    `port=${runningPort}`,
+    `childUptimeMs=${Math.max(0, now - startAt)}`,
+    `platform=${process.platform}`,
+    `node=${process.version}`,
+    `cwd=${process.cwd()}`,
+  ];
+
+  if (childPid) {
+    lines.push("process table snapshot:");
+    if (process.platform === "win32") {
+      lines.push(safeCommandOutput(`tasklist /FI "PID eq ${childPid}"`));
+    } else {
+      lines.push(safeCommandOutput(`ps -o pid,ppid,pgid,stat,etime,command -p ${childPid}`));
+    }
+  }
+
+  if (signal === "SIGKILL") {
+    lines.push("note=SIGKILL cannot be trapped by target process; source is external");
+    lines.push(...collectKillHints());
+  }
+
+  appendCrashLog(lines);
+}
+
 function checkPort(port, host = "127.0.0.1") {
   return new Promise((resolve) => {
     const socket = new net.Socket();
@@ -595,6 +681,73 @@ function hasOpenClawBinary() {
   }
 }
 
+function detectQmdBinary() {
+  try {
+    const qmdPath = execSync("command -v qmd", {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+    if (qmdPath) return qmdPath;
+  } catch {
+    // ignore
+  }
+
+  if (process.platform === "darwin") {
+    const candidate = "/opt/homebrew/bin/qmd";
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+function ensureQmdInstalled() {
+  if (process.env.CLAWPAD_SKIP_QMD === "1") {
+    console.log("  ↩︎ Skipping QMD install (CLAWPAD_SKIP_QMD=1).");
+    return { installed: false, path: detectQmdBinary() };
+  }
+
+  const existing = detectQmdBinary();
+  if (existing) {
+    return { installed: true, path: existing };
+  }
+
+  if (process.platform === "darwin") {
+    try {
+      execSync("brew --version", { stdio: "ignore" });
+      console.log("  ⏳ Installing QMD with Homebrew...");
+      execSync("brew install qmd", { stdio: "inherit" });
+    } catch (err) {
+      const message = err && err.message ? err.message : String(err);
+      console.warn(`  ⚠️  QMD Homebrew install failed: ${message}`);
+    }
+  } else if (process.platform === "linux") {
+    try {
+      console.log("  ⏳ Installing QMD from upstream installer...");
+      execSync(`curl -fsSL ${QMD_INSTALL_SCRIPT_URL} | bash`, { stdio: "inherit" });
+    } catch (err) {
+      const message = err && err.message ? err.message : String(err);
+      console.warn(`  ⚠️  QMD installer failed: ${message}`);
+    }
+  } else {
+    console.log(`  ↩︎ QMD auto-install not supported on ${process.platform}.`);
+  }
+
+  const afterInstall = detectQmdBinary();
+  if (afterInstall) {
+    return { installed: true, path: afterInstall };
+  }
+  return { installed: false, path: null };
+}
+
+function getOnboardingSentinelPath() {
+  return path.join(resolveOpenClawStateDir(), "clawpad", "onboarding-complete.json");
+}
+
+function hasCompletedOnboarding() {
+  return fs.existsSync(getOnboardingSentinelPath());
+}
+
 function resolveWorkspaceDir(config) {
   const workspace = config?.agents?.defaults?.workspace;
   if (typeof workspace === "string" && workspace.trim()) {
@@ -638,6 +791,32 @@ function copyDir(src, dest) {
   }
 }
 
+function ensureBundledSkillInstalled(workspaceDir, skillName) {
+  if (!workspaceDir || !skillName) {
+    return { installed: false, reason: "invalid-input" };
+  }
+
+  const bundledSkillPath = path.join(ROOT_DIR, "skills", skillName);
+  if (!fs.existsSync(bundledSkillPath)) {
+    return { installed: false, reason: "missing-bundled-skill" };
+  }
+
+  const skillsDir = path.join(workspaceDir, "skills");
+  const targetSkillPath = path.join(skillsDir, skillName);
+
+  if (fs.existsSync(targetSkillPath)) {
+    return { installed: false, reason: "already-installed" };
+  }
+
+  try {
+    fs.mkdirSync(skillsDir, { recursive: true });
+    copyDir(bundledSkillPath, targetSkillPath);
+    return { installed: true, reason: "installed" };
+  } catch (err) {
+    return { installed: false, reason: (err && err.message) || "copy-failed" };
+  }
+}
+
 function migrateLegacyPages(fromDir, toDir, mode) {
   if (!fs.existsSync(fromDir)) {
     return { ok: false, reason: "missing" };
@@ -713,7 +892,7 @@ async function maybeMigrateLegacyPages(config, resolvedPagesDir) {
   return { pagesDir: targetDir, migrated: migrated.ok };
 }
 
-function applyIntegrationConfig(config, pagesDir) {
+function applyIntegrationConfig(config, pagesDir, qmdPath) {
   const next = config && typeof config === "object" ? config : {};
   next.plugins = next.plugins || {};
   next.plugins.entries = next.plugins.entries || {};
@@ -729,6 +908,17 @@ function applyIntegrationConfig(config, pagesDir) {
 
   next.agents = next.agents || {};
   next.agents.defaults = next.agents.defaults || {};
+  const memory = next.agents.defaults.memory || {};
+  const memoryQmd = memory.qmd || {};
+  next.agents.defaults.memory = {
+    ...memory,
+    backend: "qmd",
+    qmd: {
+      ...memoryQmd,
+      ...(qmdPath ? { bin: qmdPath } : {}),
+    },
+  };
+
   const memorySearch = next.agents.defaults.memorySearch || {};
   const extraPaths = Array.isArray(memorySearch.extraPaths) ? [...memorySearch.extraPaths] : [];
   if (!extraPaths.includes(pagesDir)) {
@@ -742,18 +932,21 @@ function applyIntegrationConfig(config, pagesDir) {
   return next;
 }
 
-function needsIntegrationPatch(config, pagesDir) {
-  const entry = config?.plugins?.entries?.clawpad;
+function needsIntegrationPatch(config, pagesDir, qmdPath) {
+  const entry = config?.plugins?.entries?.["openclaw-plugin"];
   const configuredPages =
     entry?.config?.pagesDir || entry?.config?.pages_dir;
   const pluginEnabled = entry?.enabled === true;
   const extraPaths = config?.agents?.defaults?.memorySearch?.extraPaths;
   const hasExtraPath = Array.isArray(extraPaths) && extraPaths.includes(pagesDir);
+  const memoryBackend = config?.agents?.defaults?.memory?.backend;
+  const configuredQmdBin = config?.agents?.defaults?.memory?.qmd?.bin;
+  const qmdConfigured = memoryBackend === "qmd" && (!qmdPath || configuredQmdBin === qmdPath);
 
-  return !(pluginEnabled && configuredPages === pagesDir && hasExtraPath);
+  return !(pluginEnabled && configuredPages === pagesDir && hasExtraPath && qmdConfigured);
 }
 
-async function integrateWithOpenClaw(pagesDir) {
+async function integrateWithOpenClaw(pagesDir, qmdPath) {
   if (!shouldIntegrate) return;
   if (!hasOpenClawBinary()) return;
 
@@ -761,7 +954,12 @@ async function integrateWithOpenClaw(pagesDir) {
   const pluginInstalled = isPluginInstalled(config);
   const workspaceDir = resolveWorkspaceDir(config);
 
-  const needsConfigPatch = needsIntegrationPatch(config, pagesDir);
+  const workspaceManagerSkill = ensureBundledSkillInstalled(workspaceDir, "workspace-manager");
+  if (workspaceManagerSkill.installed) {
+    console.log("  ✅ Installed workspace-manager skill in OpenClaw workspace.");
+  }
+
+  const needsConfigPatch = needsIntegrationPatch(config, pagesDir, qmdPath);
   const needsAgentsNote = fs.existsSync(path.join(workspaceDir, "AGENTS.md"));
 
   if (!pluginInstalled && noPrompt && !autoYes) {
@@ -786,7 +984,7 @@ async function integrateWithOpenClaw(pagesDir) {
   }
 
   if (needsConfigPatch) {
-    const patched = applyIntegrationConfig(config, pagesDir);
+    const patched = applyIntegrationConfig(config, pagesDir, qmdPath);
     writeOpenClawConfig(configPath, patched);
   }
 
@@ -797,6 +995,43 @@ async function integrateWithOpenClaw(pagesDir) {
   console.log("  ✅ OpenClaw integration configured. Restart the gateway to apply.");
 }
 
+function isWorkspaceEmpty(pagesDir) {
+  try {
+    const entries = fs
+      .readdirSync(pagesDir, { withFileTypes: true })
+      .filter((entry) => !entry.name.startsWith("."));
+    return entries.length === 0;
+  } catch {
+    return true;
+  }
+}
+
+function ensureSetupSignal(pagesDir, options = {}) {
+  const signalPath = path.join(pagesDir, ".clawpad-needs-setup");
+  const force = options.force === true;
+
+  try {
+    fs.mkdirSync(pagesDir, { recursive: true });
+
+    if (!force && hasCompletedOnboarding()) {
+      return false;
+    }
+
+    if (!force && !isWorkspaceEmpty(pagesDir)) {
+      return false;
+    }
+
+    const payload = {
+      created: new Date().toISOString(),
+      reason: force ? "cli-setup-flag" : "first-run-empty-workspace",
+    };
+    fs.writeFileSync(signalPath, JSON.stringify(payload, null, 2), "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ─── Build Check ─────────────────────────────────────────
 function isBuilt() {
   const standaloneServer = path.join(ROOT_DIR, ".next", "standalone", "server.js");
@@ -892,7 +1127,17 @@ async function main() {
   if (!process.env.CLAWPAD_PAGES_DIR && pagesDir) {
     process.env.CLAWPAD_PAGES_DIR = pagesDir;
   }
-  await integrateWithOpenClaw(pagesDir);
+  const qmd = ensureQmdInstalled();
+  if (qmd.installed && qmd.path) {
+    console.log(`  ✅ QMD available at ${qmd.path}`);
+  } else {
+    console.log("  ⚠️  QMD unavailable. Semantic search and QMD memory backend may be limited.");
+  }
+  await integrateWithOpenClaw(pagesDir, qmd.path);
+  const setupSignalCreated = ensureSetupSignal(pagesDir, { force: shouldSetup });
+  if (setupSignalCreated) {
+    console.log("  📝 Setup signal detected. ClawPad will open onboarding.");
+  }
 
   // Build if needed
   if (!isBuilt()) {
@@ -928,7 +1173,10 @@ async function main() {
     }
   };
 
-  const handleServerClose = async (code, sawAddrInUse, runningPort) => {
+  let crashCount = 0;
+  let crashWindowStartedAt = 0;
+
+  const handleServerClose = async (code, signal, sawAddrInUse, runningPort) => {
     clearOpenTimer();
 
     if (shuttingDown) {
@@ -958,16 +1206,41 @@ async function main() {
       return;
     }
 
-    process.exit(code ?? 0);
+    const isCrash = signal != null || (typeof code === "number" && code !== 0);
+    if (isCrash) {
+      const now = Date.now();
+      if (!crashWindowStartedAt || now - crashWindowStartedAt > CRASH_RESTART_WINDOW_MS) {
+        crashWindowStartedAt = now;
+        crashCount = 0;
+      }
+      crashCount += 1;
+      const reason = signal ? `signal ${signal}` : `exit code ${code}`;
+
+      if (crashCount <= MAX_CRASH_RESTARTS) {
+        console.error(`  ⚠️  ClawPad server terminated unexpectedly (${reason}). Restarting (${crashCount}/${MAX_CRASH_RESTARTS})...`);
+        const restartDelayMs = Math.min(2_500, 500 * crashCount);
+        await sleep(restartDelayMs);
+        launchServer(runningPort);
+        return;
+      }
+
+      console.error(`  ❌ ClawPad server crashed repeatedly (${reason}). Giving up after ${MAX_CRASH_RESTARTS} restarts in ${Math.round(CRASH_RESTART_WINDOW_MS / 1000)}s.`);
+      process.exit(typeof code === "number" ? code : 1);
+      return;
+    }
+
+    process.exit(0);
   };
 
   const launchServer = (nextPort) => {
     port = nextPort;
     const runningPort = nextPort;
-    const url = `http://localhost:${port}`;
+    const setupPath = shouldSetup || setupSignalCreated ? "/setup" : "";
+    const url = `http://localhost:${port}${setupPath}`;
     console.log(`  🚀 Starting ClawPad at ${url}\n`);
 
     let sawAddrInUse = false;
+    const childStartedAt = Date.now();
     server = spawn(process.execPath, [serverPath], {
       cwd: standaloneDir,
       stdio: ["inherit", "inherit", "pipe"],
@@ -998,12 +1271,25 @@ async function main() {
       process.exit(1);
     });
 
-    server.on("close", (code) => {
+    server.on("close", (code, signal) => {
       if (forceShutdownTimer) {
         clearTimeout(forceShutdownTimer);
         forceShutdownTimer = null;
       }
-      void handleServerClose(code, sawAddrInUse, runningPort);
+
+      const terminatedUnexpectedly = !shuttingDown && (signal != null || (typeof code === "number" && code !== 0));
+      if (terminatedUnexpectedly) {
+        recordCrashDiagnostics({
+          signal,
+          code,
+          childPid: server?.pid ?? null,
+          runningPort,
+          startAt: childStartedAt,
+        });
+        console.error(`  🧭 Crash diagnostics written to ${CRASH_LOG_PATH}`);
+      }
+
+      void handleServerClose(code, signal, sawAddrInUse, runningPort);
     });
   };
 
@@ -1041,6 +1327,15 @@ async function main() {
   // Forward signals for clean shutdown
   process.on("SIGINT", () => requestShutdown("SIGINT"));
   process.on("SIGTERM", () => requestShutdown("SIGTERM"));
+
+  process.on("uncaughtException", (err) => {
+    console.error("  ❌ Uncaught exception in launcher:", err);
+    requestShutdown("SIGTERM");
+  });
+
+  process.on("unhandledRejection", (reason) => {
+    console.error("  ❌ Unhandled promise rejection in launcher:", reason);
+  });
 }
 
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawpad",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A file-based, Notion-style document workspace for OpenClaw",
   "keywords": [
     "openclaw",
@@ -26,6 +26,7 @@
   },
   "files": [
     "bin/",
+    "skills/",
     ".next/standalone/",
     ".next/static/",
     "public/",

package/public/install.sh

@@ -9,7 +9,7 @@ INSTALL_PREFIX="${CLAWPAD_PREFIX:-$HOME/.local}"
 INSTALL_TIMEOUT_SECONDS="${CLAWPAD_INSTALL_TIMEOUT_SECONDS:-180}"
 
 echo "ClawPad installer"
-echo "[1/4] Checking Node.js..."
+echo "[1/5] Checking Node.js..."
 
 if ! command -v node >/dev/null 2>&1; then
   echo "ClawPad requires Node.js ${MIN_NODE_MAJOR}+." >&2
@@ -28,7 +28,7 @@ if ! command -v npm >/dev/null 2>&1; then
   exit 1
 fi
 
-echo "[2/4] Preparing install prefix: ${INSTALL_PREFIX}"
+echo "[2/5] Preparing install prefix: ${INSTALL_PREFIX}"
 mkdir -p "${INSTALL_PREFIX}/bin"
 
 # Make npm quieter and avoid long post-install checks
@@ -37,7 +37,7 @@ export NPM_CONFIG_AUDIT=false
 export NPM_CONFIG_UPDATE_NOTIFIER=false
 export NPM_CONFIG_PROGRESS=false
 
-echo "[3/4] Installing ClawPad (this can take a minute)..."
+echo "[3/5] Installing ClawPad (this can take a minute)..."
 
 # Install clawpad CLI into user prefix
 install_args=(install -g clawpad --prefix "${INSTALL_PREFIX}")
@@ -65,8 +65,36 @@ if [ "${install_exit}" -ne 0 ]; then
   exit "${install_exit}"
 fi
 
+# Best-effort QMD install
+echo "[4/5] Checking QMD (best-effort)"
+if [ "${CLAWPAD_SKIP_QMD:-0}" = "1" ]; then
+  echo "Skipping QMD install (CLAWPAD_SKIP_QMD=1)."
+elif command -v qmd >/dev/null 2>&1; then
+  echo "QMD already installed."
+elif [ "$(uname -s)" = "Darwin" ] && command -v brew >/dev/null 2>&1; then
+  if brew install qmd; then
+    echo "QMD installed with Homebrew."
+  else
+    echo "QMD install failed via Homebrew (continuing)." >&2
+  fi
+elif [ "$(uname -s)" = "Linux" ] && command -v curl >/dev/null 2>&1; then
+  if curl -fsSL https://raw.githubusercontent.com/tobi/qmd/main/install.sh | bash; then
+    echo "QMD installed from upstream installer."
+  else
+    echo "QMD install failed via upstream script (continuing)." >&2
+  fi
+else
+  echo "QMD auto-install skipped: unsupported platform or missing installer dependency."
+fi
+
+if command -v qmd >/dev/null 2>&1; then
+  echo "QMD ready: $(qmd --version 2>/dev/null || echo qmd)"
+else
+  echo "QMD unavailable. You can install it later for semantic search."
+fi
+
 # Add prefix bin to PATH if needed
-echo "[4/4] Finalizing PATH setup"
+echo "[5/5] Finalizing PATH setup"
 if ! echo "$PATH" | grep -q "${INSTALL_PREFIX}/bin"; then
   if [ -f "$HOME/.bashrc" ]; then
     echo "export PATH=\"${INSTALL_PREFIX}/bin:\$PATH\"" >> "$HOME/.bashrc"

package/skills/README.md

@@ -0,0 +1,40 @@
+# ClawPad Skills
+
+Community skills for enhancing ClawPad workspaces.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| [workspace-manager](./workspace-manager/) | Workspace setup and organization assistant. Helps users create personalized folder structures based on their domain (engineering, research, business, creative, personal). |
+
+## Installing Skills
+
+Skills are automatically discovered by OpenClaw from `~/.openclaw/workspace/skills/`.
+
+To install a skill:
+
+```bash
+# Copy the skill folder to your OpenClaw workspace
+cp -r skills/workspace-manager ~/.openclaw/workspace/skills/
+```
+
+Or symlink for development:
+
+```bash
+ln -s $(pwd)/skills/workspace-manager ~/.openclaw/workspace/skills/workspace-manager
+```
+
+## Creating Skills
+
+See [OpenClaw Skills Documentation](https://docs.openclaw.ai/skills) for the full guide.
+
+Basic structure:
+```
+skills/
+└── your-skill/
+    ├── SKILL.md      # Main skill definition (required)
+    └── references/   # Optional supporting files
+```
+
+The `SKILL.md` file should have YAML frontmatter with `name` and `description`, followed by markdown instructions for the agent.