@agentlip/workspace 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @agentlip/workspace
+
+Workspace discovery and initialization for Agentlip.
+
+## Overview
+
+This package provides workspace discovery by walking upward from the current directory to find a `.agentlip/db.sqlite3` marker. If no workspace is found within security boundaries, it can initialize a new workspace.
+
+## Security Boundaries
+
+The upward traversal stops at:
+
+1. **Filesystem boundary** - Detected by device ID change (prevents crossing mount points)
+2. **User home directory** - Never traverses above `$HOME`
+3. **Filesystem root** - Stops at `/` (or drive root on Windows)
+
+This prevents:
+- Accidentally discovering workspaces outside the intended scope
+- Traversing into system directories
+- Crossing network mounts or containerized filesystems
+
+## API
+
+### `discoverWorkspaceRoot(startPath?: string)`
+
+Discover workspace root by walking upward from `startPath` (defaults to `cwd`).
+
+**Returns:** `WorkspaceDiscoveryResult | null`
+
+- Returns `null` if no workspace found within security boundaries
+- Returns discovery result if `.agentlip/db.sqlite3` exists in current or parent directory
+
+```typescript
+const result = await discoverWorkspaceRoot();
+if (result) {
+  console.log(`Workspace root: ${result.root}`);
+  console.log(`Database: ${result.dbPath}`);
+}
+```
+
+### `ensureWorkspaceInitialized(workspaceRoot: string)`
+
+Ensure workspace is initialized at the given directory.
+
+**Returns:** `WorkspaceInitResult`
+
+Creates:
+- `.agentlip/` directory with mode `0700` (owner rwx only)
+- `db.sqlite3` file with mode `0600` (owner rw only)
+
+Idempotent - safe to call multiple times.
+
+```typescript
+const result = await ensureWorkspaceInitialized('/path/to/project');
+console.log(`Created: ${result.created}`);
+console.log(`DB Path: ${result.dbPath}`);
+```
+
+### `discoverOrInitWorkspace(startPath?: string)`
+
+Combined discovery + initialization.
+
+**Returns:** `WorkspaceDiscoveryResult` (never null)
+
+Workflow:
+1. Attempts discovery from `startPath` (or cwd)
+2. If found, returns discovered workspace
+3. If not found, initializes workspace at `startPath` and returns it
+
+```typescript
+const result = await discoverOrInitWorkspace();
+if (result.discovered) {
+  console.log(`Found existing workspace at ${result.root}`);
+} else {
+  console.log(`Initialized new workspace at ${result.root}`);
+}
+```
+
+## Types
+
+```typescript
+interface WorkspaceDiscoveryResult {
+  /** Absolute path to workspace root directory */
+  root: string;
+  /** Absolute path to db.sqlite3 file */
+  dbPath: string;
+  /** Whether workspace was discovered (true) or initialized (false) */
+  discovered: boolean;
+}
+
+interface WorkspaceInitResult {
+  /** Absolute path to workspace root directory */
+  root: string;
+  /** Absolute path to db.sqlite3 file */
+  dbPath: string;
+  /** Whether workspace was newly created (true) or already existed (false) */
+  created: boolean;
+}
+```
+
+## Testing
+
+```bash
+# Run unit tests
+bun test
+
+# Run verification script
+bun verify.ts
+```
+
+## Implementation Notes
+
+- Uses `lstat()` to detect filesystem boundaries via device ID
+- Stops at user home directory using `os.homedir()`
+- Creates files with restrictive permissions (Unix-like systems only)
+- Handles symlinks safely by using `lstat()` instead of `stat()`
+- Resolves all paths to absolute form to prevent confusion

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@agentlip/workspace",
+  "version": "0.1.0",
+  "description": "Workspace discovery and initialization for Agentlip",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/phosphorco/agentlip",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phosphorco/agentlip.git",
+    "directory": "packages/workspace"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "verify": "bun verify.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * @agentlip/workspace - Workspace discovery + initialization
+ * 
+ * Provides upward workspace discovery with security boundaries:
+ * - Starts at cwd (or provided path)
+ * - Walks upward until .agentlip/db.sqlite3 exists
+ * - Stops at filesystem boundary OR user home directory
+ * - Initializes workspace at starting directory if not found
+ */
+
+import { promises as fs } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+const WORKSPACE_MARKER = '.agentlip';
+const DB_FILENAME = 'db.sqlite3';
+
+/**
+ * Result of workspace discovery
+ */
+export interface WorkspaceDiscoveryResult {
+  /** Absolute path to workspace root directory */
+  root: string;
+  /** Absolute path to db.sqlite3 file */
+  dbPath: string;
+  /** Whether workspace was discovered (true) or needs initialization (false) */
+  discovered: boolean;
+}
+
+/**
+ * Result of workspace initialization
+ */
+export interface WorkspaceInitResult {
+  /** Absolute path to workspace root directory */
+  root: string;
+  /** Absolute path to db.sqlite3 file */
+  dbPath: string;
+  /** Whether workspace was newly created (true) or already existed (false) */
+  created: boolean;
+}
+
+/**
+ * Discover workspace root by walking upward from startPath.
+ * 
+ * Stops at:
+ * - Filesystem boundary (device ID change)
+ * - User home directory (never traverse above home)
+ * 
+ * @param startPath - Directory to start search from (defaults to cwd)
+ * @returns Discovery result or null if no workspace found within boundary
+ */
+export async function discoverWorkspaceRoot(
+  startPath?: string
+): Promise<WorkspaceDiscoveryResult | null> {
+  const start = resolve(startPath ?? process.cwd());
+  const home = resolve(homedir());
+
+  // Get initial filesystem device ID
+  const startStat = await fs.lstat(start);
+  const startDevice = startStat.dev;
+  
+  let current = start;
+  
+  while (true) {
+    // Check if .agentlip/db.sqlite3 exists at current level
+    const workspaceDir = join(current, WORKSPACE_MARKER);
+    const dbPath = join(workspaceDir, DB_FILENAME);
+    
+    try {
+      await fs.access(dbPath);
+      // Found it!
+      return {
+        root: current,
+        dbPath,
+        discovered: true
+      };
+    } catch {
+      // Not found, continue upward
+    }
+    
+    // Check boundary conditions before going up
+    const parent = dirname(current);
+    
+    // Reached filesystem root (parent === current)
+    if (parent === current) {
+      return null;
+    }
+    
+    // Stop traversal at user home directory (security boundary)
+    if (current === home) {
+      return null;
+    }
+    
+    // Check filesystem boundary (device ID change)
+    try {
+      const parentStat = await fs.lstat(parent);
+      if (parentStat.dev !== startDevice) {
+        // Crossed filesystem boundary
+        return null;
+      }
+    } catch {
+      // Can't stat parent - stop here
+      return null;
+    }
+    
+    current = parent;
+  }
+}
+
+/**
+ * Ensure workspace is initialized at workspaceRoot.
+ * Creates .agentlip/ directory and empty db.sqlite3 file if they don't exist.
+ * 
+ * @param workspaceRoot - Directory to initialize workspace in
+ * @returns Init result indicating whether workspace was newly created
+ */
+export async function ensureWorkspaceInitialized(
+  workspaceRoot: string
+): Promise<WorkspaceInitResult> {
+  const root = resolve(workspaceRoot);
+  const workspaceDir = join(root, WORKSPACE_MARKER);
+  const dbPath = join(workspaceDir, DB_FILENAME);
+  
+  let created = false;
+  
+  // Check if db already exists
+  try {
+    await fs.access(dbPath);
+    // Already initialized
+    return { root, dbPath, created: false };
+  } catch {
+    // Need to initialize
+  }
+  
+  // Create .agentlip directory with mode 0700 (owner rwx only)
+  try {
+    await fs.mkdir(workspaceDir, { mode: 0o700, recursive: true });
+  } catch (err: any) {
+    // If directory already exists, that's fine
+    if (err.code !== 'EEXIST') {
+      throw err;
+    }
+  }
+  
+  // Create empty db.sqlite3 with mode 0600 (owner rw only)
+  try {
+    const handle = await fs.open(dbPath, 'wx', 0o600); // x = fail if exists
+    await handle.close();
+    created = true;
+  } catch (err: any) {
+    if (err.code === 'EEXIST') {
+      // File was created between our check and now - that's fine
+      created = false;
+    } else {
+      throw err;
+    }
+  }
+  
+  return { root, dbPath, created };
+}
+
+/**
+ * Discover workspace or initialize if not found.
+ * 
+ * Combines discovery + initialization:
+ * - First tries to discover workspace by walking upward
+ * - If not found, initializes workspace at startPath
+ * 
+ * @param startPath - Directory to start search from (defaults to cwd)
+ * @returns Discovery result (never null)
+ */
+export async function discoverOrInitWorkspace(
+  startPath?: string
+): Promise<WorkspaceDiscoveryResult> {
+  const start = resolve(startPath ?? process.cwd());
+  
+  // Try discovery first
+  const discovered = await discoverWorkspaceRoot(start);
+  if (discovered) {
+    return discovered;
+  }
+  
+  // No workspace found - initialize at start path
+  const initialized = await ensureWorkspaceInitialized(start);
+  
+  return {
+    root: initialized.root,
+    dbPath: initialized.dbPath,
+    discovered: false
+  };
+}