feat(cli): add nerve init --from to clone workspace from git

Made-with: Cursor

README.md

@@ -1,165 +1,3 @@
 # nerve
 
-**Observation engine for autonomous agents** — sense the world, react to changes, run workflows.
+Observation engine — Sense, Reflex, Workflow
-
-Nerve is a lightweight daemon that continuously observes external state through **Senses**, reacts via declarative **Reflexes**, and orchestrates multi-step **Workflows**. Built for the [Uncaged](https://github.com/uncaged) agent framework.
-
-## Core Concepts
-
-```
-External World → Sense → Signal → Reflex → Workflow → Log
-                  ↑                                     ↑
-              "what to observe"                  "what to do"
-```
-
-| Concept | Metaphor | Role |
-|---------|----------|------|
-| **Sense** | 👁️ Perception | A `compute()` function that samples or derives data. Each sense has its own SQLite database. |
-| **Reflex** | ⚡ Reaction | Declarative trigger — interval-based, event-driven, or both. Connects senses to actions. |
-| **Signal** | 📡 Notification | Emitted when a sense returns non-null. Other reflexes can listen for signals. |
-| **Workflow** | 🔧 Action | Stateful multi-step execution with Roles (actors) and a Moderator (coordinator). |
-| **Log** | 📝 Record | Immutable audit trail. Queryable by senses, but **cannot** trigger reflexes (prevents feedback loops). |
-
-Three extension points, fully orthogonal — a Sense doesn't know when it runs, a Reflex doesn't know what it computes, a Workflow doesn't know why it was triggered.
-
-## Packages
-
-| Package | Description |
-|---------|-------------|
-| [`@uncaged/nerve-core`](./packages/core) | Shared types and config parser |
-| [`@uncaged/nerve-daemon`](./packages/daemon) | The observation engine — kernel, sense runtime, reflex scheduler, workflow manager |
-| [`@uncaged/nerve-cli`](./packages/cli) | CLI tool (`nerve`) — init, start, stop, logs, query |
-
-## Quick Start
-
-```bash
-# Requirements: Node.js ≥ 22.5, pnpm
-pnpm add -g @uncaged/nerve-cli
-
-# Initialize a workspace
-mkdir my-agent && cd my-agent
-nerve init
-
-# Write a sense
-cat > senses/cpu-usage/compute.ts << 'EOF'
-export async function compute() {
-  const [load] = (await import("node:os")).loadavg();
-  return load > 2.0 ? { load } : null;  // signal only when load is high
-}
-EOF
-
-# Configure reflexes in nerve.yaml
-cat > nerve.yaml << 'EOF'
-senses:
-  cpu-usage:
-    group: system
-    throttle: 10s
-
-reflexes:
-  - kind: sense
-    sense: cpu-usage
-    interval: 30s
-EOF
-
-# Run
-nerve dev          # foreground (development)
-nerve daemon start # background (production)
-nerve status       # check health
-nerve logs         # view logs
-```
-
-## Configuration
-
-`nerve.yaml` declares senses, reflexes, and workflows:
-
-```yaml
-senses:
-  cpu-usage:
-    group: system          # senses in the same group share a worker process
-    throttle: 10s          # min interval between computes
-    timeout: 30s           # max compute duration
-    gracePeriod: 5s        # wait before first compute after startup
-
-reflexes:
-  - kind: sense
-    sense: cpu-usage
-    interval: 30s          # periodic trigger
-    on: [disk-pressure]    # also trigger on signals from other senses
-
-  - kind: workflow
-    workflow: cleanup
-    on: [disk-pressure]    # start a workflow when signal fires
-
-workflows:
-  cleanup:
-    concurrency: 1
-    overflow: drop         # discard if already running
-  code-review:
-    concurrency: 3
-    overflow: queue
-    maxQueue: 20
-```
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Kernel                                                 │
-│                                                         │
-│  ┌──────────┐   ┌──────────┐   ┌──────────┐           │
-│  │ Worker   │   │ Worker   │   │ Worker   │  (1 per   │
-│  │ (group A)│   │ (group B)│   │ (group C)│   group)  │
-│  │ sense-1  │   │ sense-3  │   │ sense-5  │           │
-│  │ sense-2  │   │ sense-4  │   │          │           │
-│  └────┬─────┘   └────┬─────┘   └────┬─────┘           │
-│       │              │              │                   │
-│       └──────────────┼──────────────┘                   │
-│                      ▼                                  │
-│              ┌──────────────┐                           │
-│              │  Signal Bus  │                           │
-│              └──────┬───────┘                           │
-│                     ▼                                   │
-│           ┌──────────────────┐                          │
-│           │ Reflex Scheduler │                          │
-│           └────────┬─────────┘                          │
-│                    ▼                                    │
-│          ┌───────────────────┐                          │
-│          │ Workflow Manager  │──→ Log Store (SQLite)    │
-│          └───────────────────┘                          │
-└─────────────────────────────────────────────────────────┘
-```
-
-- **Worker processes** — one per sense group, forked by the kernel. Isolated compute execution.
-- **Signal Bus** — in-memory pub/sub for signal distribution.
-- **Reflex Scheduler** — interval timers + signal subscriptions, with throttle/coalesce.
-- **Workflow Manager** — concurrency control (drop/queue), thread lifecycle tracking.
-- **Log Store** — WAL-mode SQLite via `node:sqlite`, with archival and retention policies.
-
-## Tech Stack
-
-- **Zero native addons** — uses Node.js built-in `node:sqlite` (DatabaseSync)
-- **Drizzle ORM** v1.0 for sense databases
-- **rslib** (rspack) for building
-- **Biome** for formatting/linting
-- **Vitest** for testing
-- **pnpm** workspaces for monorepo management
-
-## Development
-
-```bash
-git clone https://git.shazhou.work/uncaged/nerve.git
-cd nerve
-pnpm install
-pnpm build
-pnpm -r test     # run all tests
-```
-
-## Design Documents
-
-- [RFC-001: Observation Engine](./docs/rfc-001-observation-engine.md) — Sense, Signal, Reflex model
-- [RFC-002: Workflow Engine](./docs/rfc-002-workflow-engine.md) — Stateful workflow execution
-- [Coding Conventions](./docs/coding-conventions.md)
-
-## License
-
-MIT

packages/cli/README.md

@@ -1,69 +0,0 @@
-# @uncaged/nerve-cli
-
-Command-line interface for the [nerve](../../README.md) observation engine.
-
-## Install
-
-```bash
-pnpm add -g @uncaged/nerve-cli
-# or
-npx @uncaged/nerve-cli
-```
-
-Requires Node.js ≥ 22.5.
-
-## Commands
-
-### Workspace
-
-```bash
-nerve init                  # Initialize a nerve workspace (installs deps, scaffolds config)
-nerve validate              # Validate nerve.yaml configuration
-```
-
-### Daemon Management
-
-```bash
-nerve daemon start          # Start the daemon (background)
-nerve daemon stop           # Stop the daemon
-nerve daemon status         # Check daemon health
-nerve daemon restart        # Restart the daemon
-nerve daemon logs           # Tail daemon logs
-```
-
-### Development
-
-```bash
-nerve dev                   # Run in foreground mode (no daemon, Ctrl+C to stop)
-```
-
-### Querying
-
-```bash
-nerve logs                  # View structured logs
-nerve sense query <name>    # Query a sense's SQLite database
-nerve sense schema <name>   # Show a sense's database schema
-nerve status                # Daemon health summary
-```
-
-### Workflows
-
-```bash
-nerve workflow list         # List workflow runs
-nerve workflow show <runId> # Show workflow run details
-```
-
-### Top-level Aliases
-
-For convenience, these aliases are available:
-
-```bash
-nerve start    → nerve daemon start
-nerve stop     → nerve daemon stop
-nerve status   → nerve daemon status
-nerve logs     → nerve daemon logs
-```
-
-## License
-
-MIT

packages/cli/src/cli.ts

@@ -12,6 +12,26 @@ import { storeCommand } from "./commands/store.js";
 import { validateCommand } from "./commands/validate.js";
 import { workflowCommand } from "./commands/workflow.js";
 
+/**
+ * Citty picks the first non-flag token as a subcommand name. Rewrite
+ * `nerve init --from <url>` so the URL is not mistaken for `workflow`/`workspace`.
+ */
+function normalizeNerveArgv(argv: string[]): string[] {
+  const initIdx = argv.indexOf("init");
+  if (initIdx === -1) return argv;
+  const tail = argv.slice(initIdx + 1);
+  const fromAt = tail.indexOf("--from");
+  if (fromAt === -1) return argv;
+  const beforeFrom = tail.slice(0, fromAt);
+  if (beforeFrom.some((a) => !a.startsWith("-"))) return argv;
+  const next = tail[fromAt + 1];
+  if (next === undefined || next.startsWith("-")) return argv;
+  const reserved = new Set(["workflow", "workspace"]);
+  if (reserved.has(next)) return argv;
+  const mergedTail = [...tail.slice(0, fromAt), `--from=${next}`, ...tail.slice(fromAt + 2)];
+  return [...argv.slice(0, initIdx + 1), ...mergedTail];
+}
+
 const main = defineCommand({
   meta: {
     name: "nerve",
@@ -32,4 +52,4 @@ const main = defineCommand({
   },
 });
 
-runMain(main);
+runMain(main, { rawArgs: normalizeNerveArgv(process.argv.slice(2)) });

packages/cli/src/commands/init.ts

@@ -1,5 +1,5 @@
 import { execFile, spawn } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 
@@ -236,6 +236,76 @@ async function verifyNodeSqlite(): Promise<boolean> {
   }
 }
 
+function isNerveRootNonEmpty(nerveRoot: string): boolean {
+  if (!existsSync(nerveRoot)) return false;
+  return readdirSync(nerveRoot).length > 0;
+}
+
+async function runInitFromGit(url: string): Promise<void> {
+  const trimmed = url.trim();
+  if (trimmed.length === 0) {
+    process.stderr.write("❌ --from requires a non-empty git URL.\n");
+    process.exit(1);
+  }
+
+  const nerveRoot = getNerveRoot();
+  if (isNerveRootNonEmpty(nerveRoot)) {
+    process.stderr.write(
+      `❌ ${nerveRoot} already exists and is not empty. Remove it (or empty it) before using --from.\n`,
+    );
+    process.exit(1);
+  }
+
+  try {
+    await execFileAsync("git", ["--version"]);
+  } catch {
+    process.stderr.write("❌ git is not available. Install git and retry.\n");
+    process.exit(1);
+  }
+
+  try {
+    await execFileAsync("pnpm", ["--version"]);
+  } catch {
+    process.stderr.write("❌ pnpm is not available. Install pnpm and retry.\n");
+    process.exit(1);
+  }
+
+  process.stdout.write(`Cloning ${trimmed} → ${nerveRoot} …\n`);
+  try {
+    await runCommand("git", ["clone", trimmed, nerveRoot], process.cwd());
+  } catch {
+    process.stderr.write("❌ git clone failed.\n");
+    process.exit(1);
+  }
+
+  if (!existsSync(join(nerveRoot, "nerve.yaml"))) {
+    process.stdout.write(`⚠️ ${join(nerveRoot, "nerve.yaml")} not found after clone.\n`);
+  }
+  if (!existsSync(join(nerveRoot, "package.json"))) {
+    process.stdout.write(`⚠️ ${join(nerveRoot, "package.json")} not found after clone.\n`);
+  }
+
+  process.stdout.write("Installing dependencies with pnpm …\n");
+  try {
+    await runCommand("pnpm", ["install", "--no-cache"], nerveRoot);
+  } catch {
+    process.stdout.write(
+      `⚠️ pnpm install failed. Try manually:\n   cd ${nerveRoot} && pnpm install --no-cache\n`,
+    );
+  }
+
+  if (!(await verifyNodeSqlite())) {
+    process.stdout.write(
+      "⚠️ Built-in SQLite (node:sqlite) is not available in this Node.js build. " +
+        "The daemon requires Node.js 22.5 or newer with SQLite enabled.\n",
+    );
+  }
+
+  process.stdout.write(
+    `✅ Workspace cloned to ${nerveRoot}\n\n💡 Next steps:\n   1. Review nerve.yaml and install any missing tooling.\n   2. Run \`nerve start\` to launch the daemon.\n`,
+  );
+}
+
 async function runInitWorkspace(force: boolean): Promise<void> {
   const nerveRoot = getNerveRoot();
 
@@ -294,7 +364,7 @@ export const initCommand = defineCommand({
   meta: {
     name: "init",
     description:
-      "Initialize workspace (nerve init) or scaffold templates (nerve init workflow <name>)",
+      "Initialize workspace (nerve init), clone from git (nerve init --from <url>), or scaffold templates (nerve init workflow <name>)",
   },
   args: {
     force: {
@@ -302,12 +372,21 @@ export const initCommand = defineCommand({
       description: "Reinitialize even if workspace already exists (preserves data/)",
       default: false,
     },
+    from: {
+      type: "string",
+      description: "Clone an existing git repo into ~/.uncaged-nerve instead of scaffolding",
+      required: false,
+    },
   },
   subCommands: {
     workflow: initWorkflowCommand,
     workspace: initWorkspaceCommand,
   },
   async run({ args }) {
+    if (args.from !== undefined) {
+      await runInitFromGit(String(args.from));
+      return;
+    }
     await runInitWorkspace(args.force);
   },
 });

packages/core/README.md

@@ -1,39 +0,0 @@
-# @uncaged/nerve-core
-
-Shared types and configuration parser for the [nerve](../../README.md) observation engine.
-
-## What's Inside
-
-- **Type definitions** — `Signal`, `SenseConfig`, `ReflexConfig`, `WorkflowConfig`, `NerveConfig`, and all related types
-- **Config parser** — `parseNerveConfig(yaml)` validates and parses `nerve.yaml` into a typed `NerveConfig`
-- **Result type** — `Result<T>` with `ok()` / `err()` helpers for explicit error handling (no thrown exceptions)
-
-## Usage
-
-```typescript
-import { parseNerveConfig, ok, err } from "@uncaged/nerve-core";
-import type { NerveConfig, Signal, Result } from "@uncaged/nerve-core";
-
-const result: Result<NerveConfig> = parseNerveConfig(yamlString);
-if (result.ok) {
-  console.log(result.value.senses);
-}
-```
-
-## Duration Format
-
-Config fields like `throttle`, `timeout`, and `interval` accept human-readable durations:
-
-- `5s` — 5 seconds
-- `10m` — 10 minutes
-- `1h` — 1 hour
-
-## Install
-
-```bash
-pnpm add @uncaged/nerve-core
-```
-
-## License
-
-MIT

packages/daemon/README.md

@@ -1,57 +0,0 @@
-# @uncaged/nerve-daemon
-
-The observation engine runtime for [nerve](../../README.md) — runs senses, routes signals, schedules reflexes, and manages workflows.
-
-## Architecture
-
-| Module | Responsibility |
-|--------|---------------|
-| **Kernel** | Top-level orchestrator — spawns workers, wires up signal bus, scheduler, and workflow manager. Supports hot reload and graceful shutdown. |
-| **Sense Runtime** | Per-sense SQLite database (via `node:sqlite` + Drizzle ORM), migration runner, peer DB read access. |
-| **Sense Worker** | Forked child process — one per sense group. Runs compute functions in isolation. |
-| **Signal Bus** | In-memory pub/sub. Sense computes emit signals; reflexes and workflows subscribe. |
-| **Reflex Scheduler** | Drives compute triggers — interval timers, signal-based events, throttle/coalesce logic. |
-| **Workflow Manager** | Concurrency control (drop/queue), thread lifecycle, worker process management (RFC-002). |
-| **Log Store** | Structured log storage in WAL-mode SQLite. Supports retention policies, archival to JSONL, and workflow run tracking. |
-| **Blob Store** | Binary artifact storage for workflow outputs. |
-| **File Watcher** | Watches `nerve.yaml` and sense files for hot reload. |
-| **Daemon IPC** | Unix socket server for CLI ↔ daemon communication. |
-
-## Key Design Decisions
-
-- **One worker process per sense group** — isolation between groups, shared compute within a group
-- **`node:sqlite` (DatabaseSync)** — zero native addons, WAL mode, built into Node.js ≥ 22.5
-- **Throttle + coalesce** — if compute is in-flight, at most one pending trigger is queued (no unbounded accumulation)
-- **Log ≠ Signal** — logs are queryable data assets but cannot trigger reflexes (prevents feedback loops)
-
-## Usage
-
-The daemon is typically started via the CLI (`nerve daemon start`), but can be used programmatically:
-
-```typescript
-import { createKernel } from "@uncaged/nerve-daemon";
-
-const kernel = await createKernel(nerveRoot);
-await kernel.ready;
-
-// Trigger a sense manually
-kernel.triggerSense("cpu-usage");
-
-// Check health
-const health = kernel.getHealth();
-
-// Graceful shutdown
-await kernel.stop();
-```
-
-## Install
-
-```bash
-pnpm add @uncaged/nerve-daemon
-```
-
-Requires Node.js ≥ 22.5 (for `node:sqlite`).
-
-## License
-
-MIT