chore: remove gitea-access rule from project (belongs in agent local skills)

- Add .cursor/rules/no-dynamic-import.mdc: ban dynamic import() in
  production code with documented exceptions
- Add .cursor/rules/gitea-access.mdc: tea CLI usage guide
- Add explanatory comments on the 2 legitimate dynamic imports in
  sense-runtime.ts and workflow-worker.ts

.cursor/rules/no-dynamic-import.mdc

@@ -0,0 +1,34 @@
+---
+description: Ban dynamic import() in production code — use static imports instead
+globs: packages/*/src/**/*.ts
+alwaysApply: true
+---
+
+# No Dynamic Import in Production Code
+
+## Rule
+
+Do NOT use `await import()` or dynamic `import()` expressions in production source code.
+Always use static top-level `import` statements.
+
+## Why
+
+- Static imports enable tree-shaking and bundler optimizations
+- They make dependencies explicit and discoverable at a glance
+- Dynamic imports of Node built-ins or project modules add unnecessary async overhead
+
+## Exceptions (must include a comment explaining why)
+
+1. **`sense-runtime.ts`** — loads user-authored sense modules whose paths are only known at runtime
+2. **`workflow-worker.ts`** — loads user-authored workflow modules whose paths are only known at runtime
+
+When suppressing, add a comment directly above:
+
+```ts
+// Dynamic import required: user module path resolved at runtime
+const mod = await import(senseIndexPath);
+```
+
+## Test Files
+
+Test files (`__tests__/**`) are exempt — dynamic import after `vi.mock()` is standard vitest practice.

docs/skill-publish.md

@@ -56,9 +56,10 @@ pnpm -r run build
 
 ```bash
 # Only publish packages that have version bumps
-cd packages/core && npm publish --access public
-cd packages/daemon && npm publish --access public
-cd packages/cli && npm publish --access public
+# MUST use pnpm publish (not npm) — pnpm converts workspace:* to real versions
+cd packages/core && pnpm publish --access public --no-git-checks
+cd packages/daemon && pnpm publish --access public --no-git-checks
+cd packages/cli && pnpm publish --access public --no-git-checks
 ```
 
 ### 5. Commit & tag

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/nerve-cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "bin": {
     "nerve": "dist/cli.js"
@@ -14,6 +14,7 @@
     "access": "public"
   },
   "scripts": {
+    "prepublishOnly": "bash ../../scripts/prepublish-check.sh",
     "build": "tsup",
     "test": "vitest run"
   },

packages/cli/src/__tests__/daemon-cli.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+
+import { daemonCommand } from "../commands/daemon.js";
+import { devCommand } from "../commands/dev.js";
+import { daemonStartCommand } from "../commands/start.js";
+
+describe("nerve daemon command group", () => {
+  it("exposes start, stop, status, restart, and logs subcommands", () => {
+    const subs = daemonCommand.subCommands;
+    expect(subs).toBeDefined();
+    if (!subs) {
+      throw new Error("expected daemonCommand.subCommands");
+    }
+    expect(Object.keys(subs).sort()).toEqual(["logs", "restart", "start", "status", "stop"]);
+  });
+
+  it("shares the same start command object as top-level nerve start alias", () => {
+    const subs = daemonCommand.subCommands;
+    expect(subs?.start).toBe(daemonStartCommand);
+  });
+});
+
+describe("nerve dev", () => {
+  it("is a foreground dev command", () => {
+    expect(devCommand.meta?.name).toBe("dev");
+    expect(devCommand.meta?.description).toMatch(/foreground/i);
+  });
+});

packages/cli/src/cli.ts

@@ -1,9 +1,11 @@
 import { defineCommand, runMain } from "citty";
 
+import { daemonCommand } from "./commands/daemon.js";
+import { devCommand } from "./commands/dev.js";
 import { initCommand } from "./commands/init.js";
 import { logsCommand } from "./commands/logs.js";
 import { senseCommand } from "./commands/sense.js";
-import { startCommand } from "./commands/start.js";
+import { daemonStartCommand } from "./commands/start.js";
 import { statusCommand } from "./commands/status.js";
 import { stopCommand } from "./commands/stop.js";
 import { storeCommand } from "./commands/store.js";
@@ -17,7 +19,9 @@ const main = defineCommand({
   },
   subCommands: {
     init: initCommand,
-    start: startCommand,
+    daemon: daemonCommand,
+    dev: devCommand,
+    start: daemonStartCommand,
     stop: stopCommand,
     status: statusCommand,
     logs: logsCommand,

packages/cli/src/commands/daemon.ts

@@ -0,0 +1,31 @@
+import { defineCommand } from "citty";
+
+import { logsCommand } from "./logs.js";
+import { daemonStartCommand, runDaemonStartCommand } from "./start.js";
+import { statusCommand } from "./status.js";
+import { runStopCommand, stopCommand } from "./stop.js";
+
+const daemonRestartCommand = defineCommand({
+  meta: {
+    name: "restart",
+    description: "Stop then start the nerve daemon",
+  },
+  async run() {
+    await runStopCommand();
+    await runDaemonStartCommand();
+  },
+});
+
+export const daemonCommand = defineCommand({
+  meta: {
+    name: "daemon",
+    description: "Manage the nerve background daemon",
+  },
+  subCommands: {
+    start: daemonStartCommand,
+    stop: stopCommand,
+    status: statusCommand,
+    restart: daemonRestartCommand,
+    logs: logsCommand,
+  },
+});

packages/cli/src/commands/dev.ts

@@ -0,0 +1,17 @@
+import { defineCommand } from "citty";
+
+import { runForegroundKernelSession } from "../run-foreground-kernel.js";
+import { loadDaemonModule } from "../workspace-daemon.js";
+import { getNerveRoot } from "../workspace.js";
+
+export const devCommand = defineCommand({
+  meta: {
+    name: "dev",
+    description: "Run the nerve kernel in the foreground (development mode)",
+  },
+  async run() {
+    const nerveRoot = getNerveRoot();
+    const { createKernel } = await loadDaemonModule(nerveRoot);
+    await runForegroundKernelSession(nerveRoot, createKernel);
+  },
+});

packages/cli/src/commands/init.ts

@@ -1,5 +1,7 @@
+import { spawn, execFile } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { promisify } from "node:util";
 
 import { defineCommand } from "citty";
 
@@ -42,6 +44,8 @@ const GITIGNORE = `data/
 node_modules/
 `;
 
+const execFileAsync = promisify(execFile);
+
 const CPU_SCHEMA_TS = `import { integer, real, sqliteTable, text } from "drizzle-orm/sqlite-core";
 
 export const cpuUsage = sqliteTable("cpu_usage", {
@@ -90,7 +94,6 @@ function writeFile(filePath: string, content: string): void {
 }
 
 async function runCommand(cmd: string, args: string[], cwd: string): Promise<void> {
-  const { spawn } = await import("node:child_process");
   await new Promise<void>((resolve, reject) => {
     const child = spawn(cmd, args, { cwd, stdio: "inherit" });
     child.on("close", (code) => {
@@ -102,10 +105,6 @@ async function runCommand(cmd: string, args: string[], cwd: string): Promise<voi
 }
 
 async function detectPackageManager(): Promise<{ cmd: string; installArgs: string[] }> {
-  const { execFile } = await import("node:child_process");
-  const { promisify } = await import("node:util");
-  const execFileAsync = promisify(execFile);
-
   for (const pm of ["pnpm", "yarn", "npm"]) {
     try {
       await execFileAsync(pm, ["--version"]);
@@ -223,9 +222,6 @@ async function tryRequireSqlite(nerveRoot: string): Promise<boolean> {
   try {
     const modulePath = join(nerveRoot, "node_modules", "better-sqlite3");
     // Use a child process to test if the native module loads
-    const { execFile } = await import("node:child_process");
-    const { promisify } = await import("node:util");
-    const execFileAsync = promisify(execFile);
     await execFileAsync("node", ["-e", `require(${JSON.stringify(modulePath)})`], {
       cwd: nerveRoot,
       timeout: 10_000,

packages/cli/src/commands/start.ts

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import { createWriteStream, existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -5,11 +6,10 @@ import { fileURLToPath } from "node:url";
 
 import { defineCommand } from "citty";
 
-import { runForegroundKernelSession } from "../run-foreground-kernel.js";
-import { loadDaemonModule } from "../workspace-daemon.js";
 import {
   getLogPath,
   getNerveRoot,
+  getSocketPath,
   isRunning,
   readPidFile,
   removePidFile,
@@ -52,15 +52,10 @@ function daemonBootstrapScript(): string {
     return bootstrapJs;
   }
   throw new Error(
-    `daemon-bootstrap.js not found next to CLI at ${bootstrapJs}. Build the CLI package (e.g. \`pnpm --filter @uncaged/nerve-cli build\`) before using background mode (\`nerve start -d\`).`,
+    `daemon-bootstrap.js not found next to CLI at ${bootstrapJs}. Build the CLI package (e.g. \`pnpm --filter @uncaged/nerve-cli build\`) before using \`nerve daemon start\`.`,
   );
 }
 
-async function runForeground(nerveRoot: string): Promise<void> {
-  const { createKernel } = await loadDaemonModule(nerveRoot);
-  await runForegroundKernelSession(nerveRoot, createKernel);
-}
-
 async function runDaemon(nerveRoot: string): Promise<void> {
   if (isRunning()) {
     const pid = readPidFile();
@@ -71,7 +66,6 @@ async function runDaemon(nerveRoot: string): Promise<void> {
   const logPath = getLogPath();
   await mkdir(join(nerveRoot, "logs"), { recursive: true });
 
-  const { spawn } = await import("node:child_process");
   const logStream = createWriteStream(logPath, { flags: "a" });
   await new Promise<void>((resolve) => {
     if (logStream.pending) logStream.once("open", () => resolve());
@@ -97,7 +91,6 @@ async function runDaemon(nerveRoot: string): Promise<void> {
 
   writePidFile(pid);
 
-  const { getSocketPath } = await import("../workspace.js");
   const ready = await waitForSocket(getSocketPath(), 5000);
 
   if (!ready || !isRunning()) {
@@ -110,29 +103,20 @@ async function runDaemon(nerveRoot: string): Promise<void> {
 
   process.stdout.write(`✅ Nerve daemon started (pid ${pid}).\n`);
   process.stdout.write(`   Logs: ${logPath}\n`);
-  process.stdout.write("   Run `nerve stop` to stop.\n");
+  process.stdout.write("   Run `nerve daemon stop` (or `nerve stop`) to stop.\n");
 }
 
-export const startCommand = defineCommand({
+/** Background daemon only — use `nerve dev` for foreground mode. */
+export async function runDaemonStartCommand(): Promise<void> {
+  await runDaemon(getNerveRoot());
+}
+
+export const daemonStartCommand = defineCommand({
   meta: {
     name: "start",
-    description: "Start the nerve daemon",
+    description: "Start the nerve daemon in the background",
   },
-  args: {
-    daemon: {
-      type: "boolean",
-      alias: "d",
-      description: "Run as background daemon",
-      default: false,
-    },
-  },
-  async run({ args }) {
-    const nerveRoot = getNerveRoot();
-
-    if (args.daemon) {
-      await runDaemon(nerveRoot);
-    } else {
-      await runForeground(nerveRoot);
-    }
+  async run() {
+    await runDaemonStartCommand();
   },
 });

packages/cli/src/commands/stop.ts

@@ -15,44 +15,49 @@ async function waitForExit(pid: number, timeoutMs: number): Promise<boolean> {
   return false;
 }
 
+/** Core stop logic — also used by `nerve daemon restart`. */
+export async function runStopCommand(): Promise<void> {
+  const pid = readPidFile();
+  if (pid === null) {
+    process.stdout.write("⚠️ No PID file found — daemon may not be running.\n");
+    return;
+  }
+
+  if (!isRunning()) {
+    process.stdout.write("⚠️ Daemon is not running (stale PID file). Cleaning up.\n");
+    removePidFile();
+    return;
+  }
+
+  process.stdout.write(`Stopping nerve daemon (pid ${pid})…\n`);
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`❌ Failed to send SIGTERM: ${msg}\n`);
+    process.exit(1);
+  }
+
+  const graceful = await waitForExit(pid, 10_000);
+  if (!graceful) {
+    process.stdout.write("⚠️ Daemon did not exit in 10s — sending SIGKILL.\n");
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // already dead
+    }
+  }
+
+  removePidFile();
+  process.stdout.write("✅ Daemon stopped.\n");
+}
+
 export const stopCommand = defineCommand({
   meta: {
     name: "stop",
     description: "Stop the nerve daemon",
   },
   async run() {
-    const pid = readPidFile();
-    if (pid === null) {
-      process.stdout.write("⚠️ No PID file found — daemon may not be running.\n");
-      return;
-    }
-
-    if (!isRunning()) {
-      process.stdout.write("⚠️ Daemon is not running (stale PID file). Cleaning up.\n");
-      removePidFile();
-      return;
-    }
-
-    process.stdout.write(`Stopping nerve daemon (pid ${pid})…\n`);
-    try {
-      process.kill(pid, "SIGTERM");
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      process.stderr.write(`❌ Failed to send SIGTERM: ${msg}\n`);
-      process.exit(1);
-    }
-
-    const graceful = await waitForExit(pid, 10_000);
-    if (!graceful) {
-      process.stdout.write("⚠️ Daemon did not exit in 10s — sending SIGKILL.\n");
-      try {
-        process.kill(pid, "SIGKILL");
-      } catch {
-        // already dead
-      }
-    }
-
-    removePidFile();
-    process.stdout.write("✅ Daemon stopped.\n");
+    await runStopCommand();
   },
 });

packages/cli/src/daemon-bootstrap.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 import { runForegroundKernelSession } from "./run-foreground-kernel.js";
 import { loadDaemonModule } from "./workspace-daemon.js";
 

packages/core/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@uncaged/nerve-core",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
+    "prepublishOnly": "bash ../../scripts/prepublish-check.sh",
     "build": "tsup",
     "test": "vitest run"
   },

packages/daemon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/nerve-daemon",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,7 @@
     "access": "public"
   },
   "scripts": {
+    "prepublishOnly": "bash ../../scripts/prepublish-check.sh",
     "build": "tsup",
     "test": "vitest run"
   },

packages/daemon/src/sense-runtime.ts

@@ -173,6 +173,7 @@ export async function loadComputeFn(senseIndexPath: string): Promise<Result<Comp
   let mod: unknown;
 
   try {
+    // Dynamic import required: user-authored sense module, path resolved at runtime
     mod = await import(senseIndexPath);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);

packages/daemon/src/workflow-worker.ts

@@ -197,6 +197,7 @@ async function loadWorkflowDefinition(
     );
   }
 
+  // Dynamic import required: user-authored workflow module, path resolved at runtime
   const mod = await import(indexPath);
   const def: unknown = mod.default ?? mod;
 

scripts/prepublish-check.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# All packages must use pnpm publish. Block npm publish unconditionally.
+
+if [ -z "$npm_execpath" ] || [[ "$npm_execpath" != *pnpm* ]]; then
+  echo "❌ Use 'pnpm publish' instead of 'npm publish'."
+  echo "   pnpm auto-converts workspace:* dependencies to real versions."
+  exit 1
+fi