memory-journal-mcp 7.7.0 → 8.0.0

package/skills/sandbox-sdk/references/api-quick-ref.md

@@ -0,0 +1,113 @@
+# Sandbox SDK API Reference
+
+Detailed API for `@cloudflare/sandbox`. For full docs: https://developers.cloudflare.com/sandbox/api/
+
+## Lifecycle
+
+```typescript
+getSandbox(binding: DurableObjectNamespace<Sandbox>, sandboxId: string, options?: SandboxOptions): Sandbox
+
+interface SandboxOptions {
+  sleepAfter?: string;     // Duration before auto-sleep (default: "10m")
+  keepAlive?: boolean;     // Prevent auto-sleep (default: false)
+  normalizeId?: boolean;   // Lowercase IDs for preview URLs (default: false)
+}
+
+await sandbox.destroy(): Promise<void>  // Immediately terminate and delete all state
+```
+
+## Commands
+
+```typescript
+await sandbox.exec(command: string, options?: ExecOptions): Promise<ExecResult>
+
+interface ExecOptions {
+  cwd?: string;           // Working directory
+  env?: Record<string, string>;  // Environment variables
+  timeout?: number;       // Timeout in ms (default: 60000)
+  stdin?: string;         // Input to command
+}
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  success: boolean;       // exitCode === 0
+}
+```
+
+## Code Interpreter
+
+```typescript
+await sandbox.createCodeContext(options?: CreateContextOptions): Promise<CodeContext>
+
+interface CreateContextOptions {
+  language?: 'python' | 'javascript' | 'typescript';  // default: 'python'
+  cwd?: string;           // Working directory (default: '/workspace')
+  envVars?: Record<string, string>;
+  timeout?: number;       // Request timeout in ms (default: 30000)
+}
+
+await sandbox.runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>
+
+interface RunCodeOptions {
+  context?: CodeContext;  // Reuse context for state persistence
+  language?: 'python' | 'javascript' | 'typescript';
+  timeout?: number;       // Execution timeout in ms (default: 60000)
+}
+
+interface ExecutionResult {
+  code: string;
+  logs: { stdout: string[]; stderr: string[] };
+  results: RichOutput[];  // text, html, png, json, etc.
+  error?: { name: string; value: string; traceback: string[] };
+  executionCount: number;
+}
+```
+
+## Files
+
+```typescript
+await sandbox.writeFile(path: string, content: string | Uint8Array): Promise<void>
+await sandbox.readFile(path: string): Promise<{ content: string }>
+await sandbox.mkdir(path: string, options?: { recursive?: boolean }): Promise<void>
+await sandbox.listFiles(path: string): Promise<FileMetadata[]>
+await sandbox.deleteFile(path: string): Promise<void>
+
+interface FileMetadata {
+  name: string;
+  path: string;
+  isDirectory: boolean;
+  size: number;
+  modifiedAt: string;
+}
+```
+
+## Ports
+
+```typescript
+await sandbox.exposePort(port: number): Promise<{ url: string; token: string }>
+await sandbox.unexposePort(port: number): Promise<void>
+await sandbox.listPorts(): Promise<PortInfo[]>
+```
+
+## Error Handling
+
+Errors include context about the operation:
+
+```typescript
+try {
+  await sandbox.exec('invalid-command')
+} catch (error) {
+  // error.message includes command and sandbox context
+}
+```
+
+For `runCode()`, check `result.error` instead of catching:
+
+```typescript
+const result = await sandbox.runCode('1/0', { language: 'python' })
+if (result.error) {
+  console.error(result.error.name) // "ZeroDivisionError"
+}
+```

package/skills/sandbox-sdk/references/examples.md

@@ -0,0 +1,52 @@
+# Sandbox SDK Examples
+
+All examples: https://github.com/cloudflare/sandbox-sdk/tree/main/examples
+
+## Example Index
+
+| Example                | Use Case                          | Key File       |
+| ---------------------- | --------------------------------- | -------------- |
+| `minimal`              | Basic setup, exec, file ops       | `src/index.ts` |
+| `code-interpreter`     | AI code execution with Workers AI | `src/index.ts` |
+| `openai-agents`        | OpenAI Agents SDK integration     | `src/index.ts` |
+| `opencode`             | OpenCode agent integration        | `src/index.ts` |
+| `claude-code`          | Claude Code agent integration     | `src/index.ts` |
+| `typescript-validator` | TypeScript compilation/validation | `src/index.ts` |
+| `authentication`       | Auth patterns for sandboxes       | `src/index.ts` |
+
+## When to Use Which Example
+
+| Building                        | Start With             |
+| ------------------------------- | ---------------------- |
+| AI code execution               | `code-interpreter`     |
+| Agent with shell + file editing | `openai-agents`        |
+| Basic command execution         | `minimal`              |
+| Code validation service         | `typescript-validator` |
+| Multi-user sandboxes            | `authentication`       |
+
+## Common Patterns from Examples
+
+**Sandbox per user/session** (from `openai-agents`):
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, `session-${sessionId}`)
+```
+
+**Code context reuse** (from `code-interpreter`):
+
+```typescript
+const pythonCtx = await sandbox.createCodeContext({ language: 'python' })
+const result = await sandbox.runCode(code, { context: pythonCtx })
+```
+
+**Resource cleanup** (from `code-interpreter`):
+
+```typescript
+try {
+  // ... use sandbox
+} finally {
+  await sandbox.destroy()
+}
+```
+
+Fetch the full example source when implementing similar patterns.

package/skills/shadcn-ui/SKILL.md

@@ -1,72 +1,37 @@
 ---
 name: shadcn-ui
-title: Skills
-description: Give your AI assistant deep knowledge of shadcn/ui components, patterns, and best practices.
+description: |
+  Use when adding, customizing, or structuring shadcn/ui components in a project.
+  Also use when dealing with `components.json`, Tailwind configuration for shadcn, or component registries.
+  Use when working with shadcn/ui, `components.json`, `lucide-react`, `radix-ui`, or Tailwind component registries.
 ---
 
-Skills give AI assistants like Claude Code project-aware context about shadcn/ui. When installed, your AI assistant knows how to find, install, compose, and customize components using the correct APIs and patterns for your project.
+# shadcn/ui Agent Workflow
 
-For example, you can ask your AI assistant to:
+When asked to work with shadcn/ui components, follow this imperative workflow to ensure you generate correct code that aligns with the project's configuration.
 
-- _"Add a login form with email and password fields."_
-- _"Create a settings page with a form for updating profile information."_
-- _"Build a dashboard with a sidebar, stats cards, and a data table."_
-- _"Switch to --preset [CODE]"_
-- _"Can you add a hero from @tailark?"_
+## 1. Context Gathering
 
-The skill reads your project's `components.json` and provides the assistant with your framework, aliases, installed components, icon library, and base library so it can generate correct code on the first try.
+Before generating any code or installing components, you must determine the project's configuration:
 
----
-
-## Install
-
-```bash
-npx skills add shadcn/ui
-```
-
-This installs the shadcn skill into your project. Once installed, your AI assistant automatically loads it when working with shadcn/ui components.
-
-Learn more about skills at [skills.sh](https://skills.sh).
-
----
-
-## What's Included
-
-The skill provides your AI assistant with the following knowledge:
+- Inspect `components.json` to find the `aliases`, `tailwind` configuration, and the `style` (e.g., `default` or `new-york`).
+- Identify the base library being used (e.g., `lucide-react` or Radix primitives).
+- Check which components are already installed in the `components/ui/` directory.
 
-### Project Context
+## 2. Component Installation & Discovery
 
-On every interaction, the skill runs `shadcn info --json` to get your project's configuration: framework, Tailwind version, aliases, base library (`radix` or `base`), icon library, installed components, and resolved file paths.
+- **Search first:** If a required component is not installed, search the documentation or registry for it.
+- **Install securely:** To install a component, use the official CLI command `npx shadcn@latest add [component]`.
+- **Registry Security:** Do NOT blindly install components from third-party or untrusted registries (e.g., via URLs) without explicitly reviewing the source code first and requesting user approval.
 
-### CLI Commands
-
-Full reference for all CLI commands: `init`, `add`, `search`, `view`, `docs`, `diff`, `info`, and `build`. Includes flags, dry-run mode, smart merge workflows, presets, and templates.
-
-### Theming and Customization
-
-How CSS variables, OKLCH colors, dark mode, custom colors, border radius, and component variants work. Includes guidance for both Tailwind v3 and v4.
-
-### Registry Authoring
-
-How to build and publish custom component registries: `registry.json` format, item types, file objects, dependencies, CSS variables, building, hosting, and user configuration.
-
-### MCP Server
-
-Setup and tools for the shadcn MCP server, which lets AI assistants search, browse, and install components from registries.
-
----
+## 3. Composition & Customization
 
-## How It Works
+When assembling components (e.g., forms, dashboards, settings pages):
 
-1. **Project detection** — The skill activates when it finds a `components.json` file in your project.
-2. **Context injection** — It runs `shadcn info --json` to read your project configuration and injects the result into the assistant's context.
-3. **Pattern enforcement** — The assistant follows shadcn/ui composition rules: using `FieldGroup` for forms, `ToggleGroup` for option sets, semantic colors, and correct base-specific APIs.
-4. **Component discovery** — The assistant uses `shadcn docs`, `shadcn search`, or MCP tools to find components and their documentation before generating code.
+- **Follow patterns:** Use established shadcn/ui composition rules. For example, use `Form` and `FormField` wrappers for forms, and `ToggleGroup` for option sets.
+- **Semantic CSS:** Use the project's semantic CSS variables (e.g., `bg-background text-foreground`, `bg-primary`) rather than hardcoded Tailwind colors.
+- **Customization:** To customize a component, edit its source code in the `components/ui/` directory directly. Do not wrap it in unnecessary outer `div`s just to apply styles if modifying the component itself is cleaner.
 
-## Learn More
+## 4. Version Upgrades
 
-- [CLI](/docs/cli) — Full CLI command reference
-- [MCP Server](/docs/mcp) — Connect the MCP server for registry access
-- [Theming](/docs/theming) — CSS variables and customization
-- [Registry](/docs/registry) — Building and publishing custom registries
-- [skills.sh](https://skills.sh) — Learn more about AI skills
+When upgrading shadcn/ui components or the CLI itself, always review the [official changelog](https://ui.shadcn.com/docs/changelog) before running update commands to ensure no breaking changes affect customized components.