rapidkit 0.37.0 → 0.37.1

package/docs/SETUP.md

@@ -0,0 +1,107 @@
+# Setup & Workflow
+
+Canonical setup reference for **maintainers** of the RapidKit npm CLI.
+
+**End users:** start with [../README.md](../README.md), [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md), and [workspace-operations.md](./workspace-operations.md).
+
+## Prerequisites
+
+- Node.js `>= 20.19.6`
+- npm ([PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md))
+
+```bash
+npm ci
+```
+
+## Build & quality gates
+
+```bash
+npm run build
+npm run validate
+npm run validate:docs
+npm run validate:contracts
+```
+
+| Command | Purpose |
+| --- | --- |
+| `validate` | typecheck + lint + format + tests |
+| `validate:docs` | markdown links, drift guard, doc examples, README smoke |
+| `validate:contracts` | generated JSON contracts + parity tests |
+
+See [ci-workflows.md](./ci-workflows.md) for GitHub Actions mapping.
+
+## Workspace CLI smoke
+
+```bash
+npm run build
+
+node dist/index.js --help
+node dist/index.js --version
+
+node dist/index.js create workspace test-ws --yes --profile polyglot
+node dist/index.js workspace list
+cd test-ws
+node ../dist/index.js bootstrap --profile polyglot
+node ../dist/index.js setup python
+node ../dist/index.js setup node --warm-deps
+node ../dist/index.js doctor workspace
+node ../dist/index.js workspace policy show
+node ../dist/index.js cache status
+node ../dist/index.js mirror status
+```
+
+## Release confidence scripts
+
+```bash
+npm run test:scenarios
+npm run test:scenarios:full
+npm run test:runtime-matrix:full
+npm run smoke:frontend-generators
+npm pack --dry-run
+```
+
+## Common development commands
+
+```bash
+npm run typecheck
+npm run lint
+npm run format:check
+npm test
+npm run test:coverage
+```
+
+Details: [DEVELOPMENT.md](./DEVELOPMENT.md).
+
+## Environment variables
+
+Bridge + Core integration:
+
+- `RAPIDKIT_DEV_PATH` — local RapidKit Core checkout
+- `RAPIDKIT_CORE_PYTHON_PACKAGE` — override Core install target
+- `RAPIDKIT_BRIDGE_FORCE_VENV=1` — force cached bridge venv
+- `RAPIDKIT_BRIDGE_UPGRADE_PIP=1` — upgrade pip in bridge venv
+- `XDG_CACHE_HOME` — bridge cache root
+
+Scenario toggles: `RAPIDKIT_SCENARIO_FULL_BOOTSTRAP`, `RAPIDKIT_SCENARIO_WORKSPACE_CREATE`
+
+General: `DEBUG`, `NODE_ENV`
+
+## Open-source release hygiene
+
+Before tagging:
+
+```bash
+npm run validate
+npm run validate:docs
+npm run security
+npm run test:scenarios
+npm pack --dry-run
+```
+
+Use placeholders in examples (never real credentials). Do not commit local coverage output unless intentional.
+
+## See also
+
+- [Documentation index](./README.md)
+- [commands-reference.md](./commands-reference.md)
+- [contracts/README.md](./contracts/README.md)

package/docs/UTILITIES.md

@@ -0,0 +1,221 @@
+# Utilities Documentation
+
+Internal cache and performance helpers for the npm CLI codebase.
+
+**End-user commands:** [doctor-command.md](./doctor-command.md) · [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md) · [../README.md](../README.md)
+
+## Cache System
+
+### Using Cache
+
+```typescript
+import { Cache, getCachedOrFetch } from './utils/cache.js';
+
+// Simple usage
+const data = await getCachedOrFetch('my-key', async () => {
+  // Heavy operation
+  return await fetchDataFromAPI();
+});
+
+// Advanced usage
+const cache = Cache.getInstance();
+
+// Save
+await cache.set('user-data', userData, '1.0');
+
+// Read
+const cached = await cache.get('user-data', '1.0');
+
+// Invalidate
+await cache.invalidate('user-data');
+
+// Clear all
+await cache.clear();
+```
+
+### Cache Features
+- **Memory cache** for fast access
+- **Disk cache** for persistence
+- **TTL**: 24 hours (configurable)
+- **Versioning**: Version support
+- **Automatic cleanup**: Auto-removal of expired cache
+
+## Performance Monitoring
+
+### Using Performance Monitor
+
+```typescript
+import { PerformanceMonitor, measure, measurePerformance } from './utils/performance.js';
+
+// Method 1: Manual timing
+const monitor = PerformanceMonitor.getInstance();
+monitor.start('my-operation');
+// ... operation
+monitor.end('my-operation');
+
+// Method 2: Helper function
+await measure('my-async-operation', async () => {
+  await doSomethingHeavy();
+});
+
+// Method 3: Decorator (for methods)
+class MyService {
+  @measurePerformance
+  async heavyOperation() {
+    // This method is automatically measured
+  }
+}
+
+// Show summary
+monitor.summary();
+
+// Get metrics
+const metrics = monitor.getMetrics();
+console.log(metrics);
+```
+
+### Use Cases
+- Measure operation timing
+- Identify bottlenecks
+- Optimize performance
+- Debug performance issues
+
+## Best Practices
+
+### Cache
+```typescript
+// ✅ Good: Use version for invalidation
+await cache.set('data', myData, '2.0');
+
+// ✅ Good: Use getCachedOrFetch
+const result = await getCachedOrFetch('expensive-op', fetchData);
+
+// ❌ Bad: Forgetting version
+await cache.set('data', myData); // default version '1.0'
+```
+
+### Performance
+```typescript
+// ✅ Good: Measure heavy operations
+await measure('database-query', () => db.query());
+
+// ✅ Good: Show summary in development
+if (process.env.NODE_ENV === 'development') {
+  monitor.summary();
+}
+
+// ❌ Bad: Measuring trivial operations
+monitor.start('simple-addition');
+const result = 1 + 1;
+monitor.end('simple-addition'); // overhead exceeds benefit
+```
+
+## Integration Example
+
+```typescript
+import { getCachedOrFetch } from './utils/cache.js';
+import { measure } from './utils/performance.js';
+import { logger } from './logger.js';
+
+async function fetchUserData(userId: string) {
+  const apiBaseUrl = process.env.API_BASE_URL ?? 'https://api.example.com';
+  return await getCachedOrFetch(
+    `user-${userId}`,
+    async () => {
+      return await measure('fetch-user-from-api', async () => {
+        logger.debug(`Fetching user ${userId} from API`);
+        const response = await fetch(`${apiBaseUrl}/users/${userId}`);
+        return await response.json();
+      });
+    },
+    '1.0'
+  );
+}
+
+// Usage
+const user = await fetchUserData('123');
+// First time: Fetches from API and caches
+// Second time: Reads from cache (fast)
+```
+
+## Environment Variables
+
+```bash
+# Enable debug mode to see cache hits/misses
+DEBUG=rapidkit:cache npm run dev
+
+# Enable performance logging
+DEBUG=rapidkit:perf npm run dev
+
+# Enable all
+DEBUG=rapidkit:* npm run dev
+```
+
+## Testing
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Cache } from './utils/cache.js';
+
+describe('Cache', () => {
+  beforeEach(async () => {
+    await Cache.getInstance().clear();
+  });
+
+  it('should cache and retrieve data', async () => {
+    const cache = Cache.getInstance();
+    await cache.set('test', { value: 42 });
+    const result = await cache.get('test');
+    expect(result).toEqual({ value: 42 });
+  });
+
+  it('should invalidate expired cache', async () => {
+    // Test with mock Date.now()
+  });
+});
+```
+
+## Migration Guide
+
+If you have existing code that you want to add caching to:
+
+```typescript
+// Before
+async function loadTemplates() {
+  const files = await fs.readdir(templateDir);
+  return files.map(parseTemplate);
+}
+
+// After
+async function loadTemplates() {
+  return await getCachedOrFetch('templates', async () => {
+    const files = await fs.readdir(templateDir);
+    return files.map(parseTemplate);
+  }, '1.0');
+}
+```
+
+## Troubleshooting
+
+### Cache not working
+```bash
+# Check cache location
+ls -la "$HOME/.rapidkit/cache/"
+
+# Clear cache manually
+rm -rf "$HOME/.rapidkit/cache/"
+
+# Check safe permissions (least privilege)
+chmod 700 "$HOME/.rapidkit"
+chmod 700 "$HOME/.rapidkit/cache"
+```
+
+### Incorrect performance metrics
+```bash
+# Make sure you're in debug mode
+export DEBUG=rapidkit:perf
+npm run dev
+
+# Check memory usage
+node --expose-gc --max-old-space-size=4096 dist/index.js
+```

package/docs/WORKSPACE_MARKER_SPEC.md

@@ -0,0 +1,276 @@
+# RapidKit Workspace Marker Specification
+
+## Overview
+
+The `.rapidkit-workspace` file is the standardized marker that identifies a RapidKit workspace. It uses a **metadata layer architecture** that allows multiple tools (npm CLI, VS Code Extension, Python Core, etc.) to add their own metadata while preserving a consistent core structure.
+
+## File Structure
+
+### Core Fields (Required)
+
+```json
+{
+  "signature": "RAPIDKIT_WORKSPACE",
+  "createdBy": "rapidkit-npm",
+  "version": "0.15.1",
+  "createdAt": "2026-02-01T12:23:31.993Z",
+  "name": "workspace-name",
+  "metadata": { ... }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `signature` | `"RAPIDKIT_WORKSPACE"` | Fixed identifier for workspace detection |
+| `createdBy` | `"rapidkit-npm" \| "rapidkit-vscode" \| "rapidkit-cli"` | Tool that originally created the workspace |
+| `version` | `string` | Version of the tool that created the workspace |
+| `createdAt` | `string` | ISO 8601 timestamp of workspace creation |
+| `name` | `string` | Workspace name |
+| `metadata` | `object` | Optional metadata layer (see below) |
+
+### Metadata Layer (Optional)
+
+The metadata layer allows each tool to store its own information without conflicts:
+
+```json
+{
+  "metadata": {
+    "vscode": {
+      "extensionVersion": "0.5.0",
+      "createdViaExtension": true,
+      "lastOpenedAt": "2026-02-01T14:30:00.000Z",
+      "openCount": 5
+    },
+    "npm": {
+      "packageVersion": "0.15.1",
+      "installMethod": "poetry",
+      "lastUsedAt": "2026-02-01T12:23:31.993Z"
+    },
+    "python": {
+      "coreVersion": "0.2.1",
+      "pythonVersion": "3.10",
+      "venvPath": ".venv"
+    },
+    "custom": {
+      "myTool": "data"
+    }
+  }
+}
+```
+
+#### VS Code Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `extensionVersion` | `string` | Extension version that last interacted |
+| `createdViaExtension` | `boolean` | Was workspace created via Extension? |
+| `lastOpenedAt` | `string` | ISO 8601 timestamp of last open |
+| `openCount` | `number` | Number of times opened in VS Code |
+
+#### npm CLI Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `packageVersion` | `string` | npm package version |
+| `installMethod` | `"poetry" \| "venv" \| "pipx"` | Install method used |
+| `lastUsedAt` | `string` | ISO 8601 timestamp of last use |
+
+#### Python Core Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `coreVersion` | `string` | RapidKit Core version |
+| `pythonVersion` | `string` | Python version used |
+| `venvPath` | `string` | Virtual environment path (relative) |
+
+## Usage Guidelines
+
+### Creating a Workspace Marker
+
+**npm package:**
+```typescript
+import { createNpmWorkspaceMarker, writeWorkspaceMarker } from './workspace-marker';
+
+const marker = createNpmWorkspaceMarker('my-workspace', '0.15.1', 'poetry');
+await writeWorkspaceMarker('/path/to/workspace', marker);
+```
+
+**VS Code Extension:**
+```typescript
+// Let npm create the marker, then add VS Code metadata
+await updateWorkspaceMetadata(workspacePath, {
+  vscode: {
+    extensionVersion: '0.5.0',
+    createdViaExtension: true,
+    lastOpenedAt: new Date().toISOString(),
+    openCount: 1,
+  },
+});
+```
+
+### Reading Workspace Metadata
+
+```typescript
+import { readWorkspaceMarker } from './workspace-marker';
+
+const marker = await readWorkspaceMarker('/path/to/workspace');
+
+if (marker) {
+  console.log('Workspace:', marker.name);
+  console.log('Created by:', marker.createdBy);
+  
+  if (marker.metadata?.vscode) {
+    console.log('Opened', marker.metadata.vscode.openCount, 'times in VS Code');
+  }
+}
+```
+
+### Updating Metadata
+
+**Always use `updateWorkspaceMetadata()` to preserve existing metadata:**
+
+```typescript
+// ✅ Correct - preserves other metadata
+await updateWorkspaceMetadata(workspacePath, {
+  vscode: {
+    extensionVersion: '0.5.0',
+    lastOpenedAt: new Date().toISOString(),
+  },
+});
+
+// ❌ Wrong - overwrites entire marker
+await writeWorkspaceMarker(workspacePath, newMarker);
+```
+
+## Benefits
+
+### 1. **Cross-Tool Compatibility**
+- npm, Extension, and future tools share the same format
+- No conflicts between different tools
+
+### 2. **Traceability**
+- Know which tool created the workspace
+- Track usage across different interfaces
+- Debug issues by checking tool versions
+
+### 3. **Extensibility**
+- New tools can add their own metadata
+- No breaking changes to core structure
+- Custom metadata for user tools
+
+### 4. **Backwards Compatibility**
+- Old markers without metadata still work
+- Metadata is optional
+- Validation checks only core fields
+
+## Migration Guide
+
+### From Legacy Markers
+
+Old format (Extension-specific):
+```json
+{
+  "signature": "RAPIDKIT_WORKSPACE",
+  "createdBy": "rapidkit-vscode",
+  "version": "0.15.1",
+  "createdAt": "2026-02-01T12:24:21.830Z",
+  "name": "alef",
+  "vscodeVersion": "0.5.0",
+  "originalCreatedBy": "rapidkit-npm"
+}
+```
+
+New format (standardized):
+```json
+{
+  "signature": "RAPIDKIT_WORKSPACE",
+  "createdBy": "rapidkit-npm",
+  "version": "0.15.1",
+  "createdAt": "2026-02-01T12:24:21.830Z",
+  "name": "alef",
+  "metadata": {
+    "vscode": {
+      "extensionVersion": "0.5.0",
+      "createdViaExtension": true,
+      "lastOpenedAt": "2026-02-01T12:24:21.830Z",
+      "openCount": 1
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **npm creates the marker** - Only npm package should create the core marker
+2. **Tools add metadata** - Other tools use `updateWorkspaceMetadata()`
+3. **Preserve existing data** - Always merge, never overwrite
+4. **Validate on read** - Use `isValidWorkspaceMarker()` to check structure
+5. **Handle missing metadata gracefully** - Metadata is always optional
+
+## Example Workflows
+
+### Workflow 1: Create workspace with npm, open in VS Code
+```
+1. User: npx rapidkit my-workspace
+2. npm: Creates marker with npm metadata
+3. User: Opens workspace in VS Code
+4. Extension: Adds VS Code metadata to existing marker
+```
+
+Result:
+```json
+{
+  "signature": "RAPIDKIT_WORKSPACE",
+  "createdBy": "rapidkit-npm",
+  "version": "0.15.1",
+  "createdAt": "2026-02-01T10:00:00.000Z",
+  "name": "my-workspace",
+  "metadata": {
+    "npm": {
+      "packageVersion": "0.15.1",
+      "installMethod": "poetry"
+    },
+    "vscode": {
+      "extensionVersion": "0.5.0",
+      "createdViaExtension": false,
+      "lastOpenedAt": "2026-02-01T11:00:00.000Z",
+      "openCount": 1
+    }
+  }
+}
+```
+
+### Workflow 2: Create workspace via Extension
+```
+1. User: Creates workspace via Extension
+2. Extension: Calls npm package to create marker
+3. npm: Creates marker with npm metadata
+4. Extension: Adds VS Code metadata
+```
+
+Result:
+```json
+{
+  "signature": "RAPIDKIT_WORKSPACE",
+  "createdBy": "rapidkit-npm",
+  "version": "0.15.1",
+  "createdAt": "2026-02-01T10:00:00.000Z",
+  "name": "my-workspace",
+  "metadata": {
+    "npm": {
+      "packageVersion": "0.15.1",
+      "installMethod": "poetry"
+    },
+    "vscode": {
+      "extensionVersion": "0.5.0",
+      "createdViaExtension": true,
+      "lastOpenedAt": "2026-02-01T10:00:00.000Z",
+      "openCount": 1
+    }
+  }
+}
+```
+
+## Version History
+
+- **v1.0** (2026-02-01): Initial specification with metadata layer architecture

package/docs/ci-workflows.md

@@ -0,0 +1,56 @@
+# CI Workflows
+
+Map of GitHub Actions workflows in this repository. Use this when editing CI to avoid overlapping coverage.
+
+## Workflows
+
+| Workflow | Path | Purpose |
+| --- | --- | --- |
+| Build / test matrix | `.github/workflows/ci.yml` | Build, lint, typecheck, tests, coverage, contract gates |
+| Workspace E2E matrix | `.github/workflows/workspace-e2e-matrix.yml` | Cross-OS workspace lifecycle smoke; setup `--warm-deps`; cache/mirror ops |
+| Windows bridge E2E | `.github/workflows/windows-bridge-e2e.yml` | Native Windows bridge and lifecycle checks |
+| E2E smoke | `.github/workflows/e2e-smoke.yml` | Focused bridge regression smoke |
+| Frontend generator smoke | `.github/workflows/frontend-generator-smoke.yml` | Official frontend generator drift gate |
+| Security | `.github/workflows/security.yml` | Security scanning and policy checks |
+
+## Consumer workspace: agent grounding CI
+
+For RapidKit **consumer workspaces** (not this CLI repo), use the copy-paste template:
+
+- [examples/ci-agent-grounding.yml](./examples/ci-agent-grounding.yml)
+
+Minimal job:
+
+```yaml
+- run: npx rapidkit pipeline --json --strict
+- run: npx rapidkit workspace agent-sync --write --refresh-context --strict --json
+```
+
+`pipeline` writes governance evidence and **auto-syncs** agent hooks (`AGENTS.md`, Copilot, Cursor, Claude) unless `RAPIDKIT_NO_AGENT_SYNC=1` or `--no-agent-sync`.
+
+## Local validation scripts
+
+| Script | Command |
+| --- | --- |
+| Runtime acceptance (default) | `npm run test:runtime-matrix` |
+| Runtime acceptance (full) | `npm run test:runtime-matrix:full` |
+| Frontend generators (dry-run) | `npm run smoke:frontend-generators` |
+| Frontend generators (network) | `npm run smoke:frontend-generators:network` |
+| Docs drift guard | `npm run check:docs-drift` |
+| README command smoke | `npm run smoke:readme` |
+
+## Recommended pre-release checks
+
+```bash
+npm run validate
+npm run validate:docs
+npm run security
+npm run security
+npm run test:runtime-matrix:full
+```
+
+## See also
+
+- [SETUP.md](./SETUP.md)
+- [DEVELOPMENT.md](./DEVELOPMENT.md)
+- [Documentation index](./README.md)