memory-journal-mcp 7.7.0 → 8.0.0

package/skills/durable-objects/references/workers.md

@@ -0,0 +1,336 @@
+# Cloudflare Workers Best Practices
+
+High-level guidance for Workers that invoke Durable Objects.
+
+## Wrangler Configuration
+
+### wrangler.jsonc (Recommended)
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-12-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  "durable_objects": {
+    "bindings": [
+      { "name": "CHAT_ROOM", "class_name": "ChatRoom" },
+      { "name": "USER_SESSION", "class_name": "UserSession" },
+    ],
+  },
+
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ChatRoom", "UserSession"] }],
+
+  // Environment variables
+  "vars": {
+    "ENVIRONMENT": "production",
+  },
+
+  // KV namespaces
+  "kv_namespaces": [{ "binding": "CONFIG", "id": "abc123" }],
+
+  // R2 buckets
+  "r2_buckets": [{ "binding": "UPLOADS", "bucket_name": "my-uploads" }],
+
+  // D1 databases
+  "d1_databases": [{ "binding": "DB", "database_id": "xyz789" }],
+}
+```
+
+### wrangler.toml (Alternative)
+
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-12-01"
+compatibility_flags = ["nodejs_compat"]
+
+[[durable_objects.bindings]]
+name = "CHAT_ROOM"
+class_name = "ChatRoom"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ChatRoom"]
+
+[vars]
+ENVIRONMENT = "production"
+```
+
+## TypeScript Types
+
+### Environment Interface
+
+```typescript
+// src/types.ts
+import { ChatRoom } from './durable-objects/chat-room'
+import { UserSession } from './durable-objects/user-session'
+
+export interface Env {
+  // Durable Objects
+  CHAT_ROOM: DurableObjectNamespace<ChatRoom>
+  USER_SESSION: DurableObjectNamespace<UserSession>
+
+  // KV
+  CONFIG: KVNamespace
+
+  // R2
+  UPLOADS: R2Bucket
+
+  // D1
+  DB: D1Database
+
+  // Environment variables
+  ENVIRONMENT: string
+  API_KEY: string // From secrets
+}
+```
+
+### Export Durable Object Classes
+
+```typescript
+// src/index.ts
+export { ChatRoom } from './durable-objects/chat-room'
+export { UserSession } from './durable-objects/user-session'
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // Worker handler
+  },
+}
+```
+
+## Worker Handler Pattern
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url)
+
+    try {
+      // Route to appropriate handler
+      if (url.pathname.startsWith('/api/rooms')) {
+        return handleRooms(request, env)
+      }
+      if (url.pathname.startsWith('/api/users')) {
+        return handleUsers(request, env)
+      }
+
+      return new Response('Not Found', { status: 404 })
+    } catch (error) {
+      console.error('Request failed:', error)
+      return new Response('Internal Server Error', { status: 500 })
+    }
+  },
+}
+
+async function handleRooms(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url)
+  const roomId = url.searchParams.get('room')
+
+  if (!roomId) {
+    return Response.json({ error: 'Missing room parameter' }, { status: 400 })
+  }
+
+  const stub = env.CHAT_ROOM.getByName(roomId)
+
+  if (request.method === 'POST') {
+    const body = await request.json<{ userId: string; message: string }>()
+    const result = await stub.sendMessage(body.userId, body.message)
+    return Response.json(result)
+  }
+
+  const messages = await stub.getMessages()
+  return Response.json(messages)
+}
+```
+
+## Request Validation
+
+```typescript
+import { z } from 'zod'
+
+const SendMessageSchema = z.object({
+  userId: z.string().min(1),
+  message: z.string().min(1).max(1000),
+})
+
+async function handleSendMessage(request: Request, env: Env): Promise<Response> {
+  const body = await request.json()
+  const result = SendMessageSchema.safeParse(body)
+
+  if (!result.success) {
+    return Response.json(
+      { error: 'Validation failed', details: result.error.issues },
+      { status: 400 }
+    )
+  }
+
+  const stub = env.CHAT_ROOM.getByName(result.data.userId)
+  const message = await stub.sendMessage(result.data.userId, result.data.message)
+  return Response.json(message)
+}
+```
+
+## Observability & Logging
+
+### Structured Logging
+
+```typescript
+function log(level: 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>) {
+  console.log(
+    JSON.stringify({
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+      ...data,
+    })
+  )
+}
+
+// Usage
+log('info', 'Request received', { path: url.pathname, method: request.method })
+log('error', 'DO call failed', { roomId, error: String(error) })
+```
+
+### Request Tracing
+
+```typescript
+async function handleRequest(request: Request, env: Env): Promise<Response> {
+  const requestId = crypto.randomUUID()
+  const startTime = Date.now()
+
+  try {
+    const response = await processRequest(request, env)
+
+    log('info', 'Request completed', {
+      requestId,
+      duration: Date.now() - startTime,
+      status: response.status,
+    })
+
+    return response
+  } catch (error) {
+    log('error', 'Request failed', {
+      requestId,
+      duration: Date.now() - startTime,
+      error: String(error),
+    })
+    throw error
+  }
+}
+```
+
+### Tail Workers (Production)
+
+For production logging, use Tail Workers to forward logs:
+
+```jsonc
+// wrangler.jsonc
+{
+  "tail_consumers": [{ "service": "log-collector" }],
+}
+```
+
+## Error Handling
+
+### Graceful DO Errors
+
+```typescript
+async function callDO(stub: DurableObjectStub<ChatRoom>, method: string): Promise<Response> {
+  try {
+    const result = await stub.getMessages()
+    return Response.json(result)
+  } catch (error) {
+    if (error instanceof Error) {
+      // DO threw an error
+      log('error', 'DO operation failed', { error: error.message })
+      return Response.json({ error: 'Service temporarily unavailable' }, { status: 503 })
+    }
+    throw error
+  }
+}
+```
+
+### Timeout Handling
+
+```typescript
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error('Timeout')), ms)
+  )
+  return Promise.race([promise, timeout])
+}
+
+// Usage
+const result = await withTimeout(stub.processData(data), 5000)
+```
+
+## CORS Handling
+
+```typescript
+function corsHeaders(): HeadersInit {
+  return {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.method === 'OPTIONS') {
+      return new Response(null, { headers: corsHeaders() })
+    }
+
+    const response = await handleRequest(request, env)
+
+    // Add CORS headers to response
+    const newHeaders = new Headers(response.headers)
+    Object.entries(corsHeaders()).forEach(([k, v]) => newHeaders.set(k, v))
+
+    return new Response(response.body, {
+      status: response.status,
+      headers: newHeaders,
+    })
+  },
+}
+```
+
+## Secrets Management
+
+Set secrets via wrangler CLI (not in config files):
+
+```bash
+wrangler secret put API_KEY
+wrangler secret put DATABASE_URL
+```
+
+Access in code:
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const apiKey = env.API_KEY // From secret
+    // ...
+  },
+}
+```
+
+## Development Commands
+
+```bash
+# Local development
+wrangler dev
+
+# Deploy
+wrangler deploy
+
+# Tail logs
+wrangler tail
+
+# List DOs
+wrangler d1 execute DB --command "SELECT * FROM _cf_DO"
+```

package/skills/gcp/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gcp
+description: |
+  Google Cloud Platform (GCP) best practices. Use when provisioning GCP infrastructure, configuring IAM, deploying to Cloud Run, GKE (Kubernetes Engine), Cloud Functions, Cloud SQL, or managing BigQuery. Do NOT trigger for generic "deploy my app" requests without clarifying the target platform.
+---
+
+# Google Cloud Platform (GCP) Best Practices
+
+**STOP.** Your knowledge of GCP may be outdated. Prefer retrieval over pre-training for any version-sensitive GCP configuration. Fetch current documentation when in doubt.
+
+Guidelines for architecting and deploying secure, scalable applications on GCP.
+
+## 1. Identity and Access Management (IAM)
+
+- **Service Accounts**: Do not use the default Compute Engine service account. Create dedicated, narrowly-scoped service accounts for each application (Cloud Run, GKE node pool, Cloud Function).
+- **Workload Identity**: Always use Workload Identity (for GKE) or Workload Identity Federation (for GitHub Actions/CI) instead of generating and storing long-lived JSON service account keys.
+- **Least Privilege**: Grant roles at the lowest level possible (Resource level > Project level > Folder level).
+
+## 2. Serverless (Cloud Run & Cloud Functions)
+
+- **Cloud Run**: Prefer Cloud Run over Cloud Functions for containerized applications. It supports multi-concurrency (handling multiple requests per instance), which significantly lowers costs and cold starts.
+- **Scaling**: Configure minimum instances (`min-instances`) to 1 or more for latency-sensitive applications to mitigate cold starts. Ensure `max-instances` is set to prevent runaway billing.
+
+## 3. Data and Storage (Cloud SQL, Cloud Storage, BigQuery)
+
+- **Cloud SQL**: Use private IPs for Cloud SQL instances. Connect to them using the Cloud SQL Auth Proxy or Serverless VPC Access connectors rather than exposing them to the public internet.
+- **Cloud Storage**: Enforce Uniform Bucket-Level Access to manage permissions solely via IAM, disabling legacy ACLs. Enable object versioning for critical buckets to protect against accidental overwrites/deletes.
+- **BigQuery**: Always partition and cluster large BigQuery tables to minimize query costs (BigQuery charges per byte processed).
+
+## 4. Networking and Security
+
+- **VPC Service Controls**: Use VPC SC to create secure perimeters around sensitive data (e.g., preventing data exfiltration from Cloud Storage or BigQuery).
+- **Cloud Armor**: Attach Google Cloud Armor to Global HTTP(S) Load Balancers to defend against DDoS attacks and implement WAF (Web Application Firewall) rules.
+
+## 5. Infrastructure as Code
+
+- **Terraform**: Use Terraform as the primary IaC tool for GCP. Store the Terraform state in a centralized, version-enabled Cloud Storage bucket with state locking enabled.

package/skills/github-actions/SKILL.md

@@ -2,11 +2,9 @@
 name: github-actions
 description: |
   Master GitHub Actions CI/CD workflows with production-grade security and
-  performance patterns. Use when writing workflow YAML, configuring CI/CD
-  pipelines, setting up matrix strategies, caching dependencies, managing
-  artifacts, or implementing reusable workflows. Triggers on "GitHub Actions",
-  "CI/CD", "workflow", "actions/checkout", "matrix strategy", "reusable
-  workflow", "SHA pinning", ".github/workflows".
+  performance patterns. Use ONLY when explicitly setting up CI/CD pipelines specifically via GitHub Actions, 
+  setting up matrix strategies, caching dependencies, managing
+  artifacts, or implementing reusable workflows. For deployment requests, use ONLY when the deploy step is inside a .github/workflows file. NOT for GitLab or autonomous-dev. NOT for Render, AWS, Azure, or GCP deployments unless explicitly triggered from within a CI/CD workflow context. Do NOT trigger for generic "deploy my app" requests without clarifying the target platform.
 ---
 
 # GitHub Actions CI/CD Engineering Standards
@@ -30,6 +28,7 @@ This skill codifies 2026 GitHub Actions best practices — secure supply chains,
 - **ALWAYS** pin to full-length commit SHAs — tags are mutable and can be hijacked
 - **ALWAYS** add a trailing comment with the version for human readability
 - **Use tools** like `step-security/harden-runner` or `pin-github-action` CLI to automate SHA resolution
+- **Resolve SHA Manually**: See [templates.md](references/templates.md) for the `gh api` command to resolve SHAs.
 - **Audit quarterly** — review all pinned SHAs when updating workflow dependencies
 
 ### Permission Hardening
@@ -56,59 +55,7 @@ jobs:
 
 ### Standard CI Template
 
-```yaml
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@<sha> # v4
-      - uses: actions/setup-node@<sha> # v4
-        with:
-          node-version-file: .node-version
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm run lint
-      - run: pnpm run typecheck
-
-  test:
-    runs-on: ubuntu-latest
-    needs: lint
-    steps:
-      - uses: actions/checkout@<sha> # v4
-      - uses: actions/setup-node@<sha> # v4
-        with:
-          node-version-file: .node-version
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm test
-
-  build:
-    runs-on: ubuntu-latest
-    needs: test
-    steps:
-      - uses: actions/checkout@<sha> # v4
-      - uses: actions/setup-node@<sha> # v4
-        with:
-          node-version-file: .node-version
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm run build
-```
+See **[templates.md](references/templates.md)** for a complete, production-ready CI workflow template.
 
 ### Key Structural Rules
 

package/skills/github-actions/references/templates.md

@@ -0,0 +1,65 @@
+# GitHub Actions Templates
+
+## Resolve SHA Manually
+
+To manually resolve a commit SHA for a GitHub Action using the GitHub CLI (`gh`):
+
+```bash
+# Resolve SHA: gh api /repos/actions/checkout/git/refs/heads/main --jq '.object.sha'
+```
+
+## Standard CI Template
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@<sha> # v4
+      - uses: actions/setup-node@<sha> # v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint
+      - run: pnpm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@<sha> # v4
+      - uses: actions/setup-node@<sha> # v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@<sha> # v4
+      - uses: actions/setup-node@<sha> # v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+```

package/skills/github-commander/SKILL.md

@@ -1,14 +1,12 @@
 ---
 name: github-commander
 description: |
-  Structured workflows for triaging GitHub issues, reviewing PRs, sprinting
-  through milestones, and running security/quality/performance audits — with
-  configurable validation gates, auto-detected security scanning, journal audit
-  trails, and human-in-the-loop checkpoints. Use this skill whenever you are
-  working on a GitHub issue, reviewing or submitting a PR, running any kind of
-  code audit, updating dependencies, or working through a milestone. Also use
-  when the user mentions issue numbers, PR numbers, milestone names, or
-  asks you to "fix", "triage", "audit", "review", or "update deps".
+  Structured workflows for GitHub issues, PRs, milestones, and code audits with validation gates and HITL checkpoints. 
+  Use when assigned a GitHub issue, reviewing a PR, sprinting through a milestone, updating dependencies, or running code audits. 
+  Also use when asked to "triage an issue", "review a PR", or "update deps". 
+  Do NOT trigger on bare verbs (e.g. "fix this"); require GitHub context. 
+  NOT for pipeline authoring (use github-actions instead).
+  Delegate all code quality, performance, and security audits to the dedicated `adversarial-*` skills instead.
 ---
 
 # GitHub Commander
@@ -35,17 +33,13 @@ Load this skill when any of these apply:
 
 ## Quick Reference
 
-| Workflow                | File                              | Purpose                                     |
-| ----------------------- | --------------------------------- | ------------------------------------------- |
-| **Issue Triage**        | `workflows/issue-triage.md`       | Fix a single GitHub issue end-to-end        |
-| **PR Review**           | `workflows/pr-review.md`          | Review a PR with validation pipeline        |
-| **Copilot Audit**       | `workflows/copilot-audit.md`      | Adversarial Copilot CLI repo/PR review      |
-| **Milestone Sprint**    | `workflows/milestone-sprint.md`   | Work through milestone issues sequentially  |
-| **Roadmap Kickoff**     | `workflows/roadmap-kickoff.md`    | Translate planning epics into Kanban issues |
-| **Update Dependencies** | `workflows/update-deps.md`        | Dependency update with audit trail          |
-| **Security Audit**      | `workflows/security-audit.md`     | Auto-detected security scanning             |
-| **Code Quality Audit**  | `workflows/code-quality-audit.md` | Static code quality analysis                |
-| **Performance Audit**   | `workflows/perf-audit.md`         | Build, bundle, runtime, test speed analysis |
+| Workflow                | File                            | Purpose                                     |
+| ----------------------- | ------------------------------- | ------------------------------------------- |
+| **Issue Triage**        | `workflows/issue-triage.md`     | Fix a single GitHub issue end-to-end        |
+| **PR Review**           | `workflows/pr-review.md`        | Review a PR with validation pipeline        |
+| **Milestone Sprint**    | `workflows/milestone-sprint.md` | Work through milestone issues sequentially  |
+| **Roadmap Kickoff**     | `workflows/roadmap-kickoff.md`  | Translate planning epics into Kanban issues |
+| **Update Dependencies** | `workflows/update-deps.md`      | Dependency update with audit trail          |
 
 ## Prerequisites
 
@@ -143,10 +137,8 @@ These entry types are used by Commander workflows for structured audit trails:
 | `implementation`         | issue-triage     | Fix implemented                             |
 | `gate_pass`              | all              | Validation gate passed                      |
 | `gate_fail`              | all              | Validation gate failed (with error details) |
-| `security_finding`       | security-audit   | Security scan finding                       |
 | `pr_submitted`           | issue-triage     | PR created and pushed                       |
 | `review_start`           | pr-review        | PR review initiated                         |
 | `review_complete`        | pr-review        | PR review completed                         |
 | `milestone_sprint_start` | milestone-sprint | Sprint started                              |
 | `deps_update`            | update-deps      | Dependency update completed                 |
-| `audit_finding`          | all audits       | Code quality or perf finding                |

package/skills/github-commander/workflows/copilot-audit.md

@@ -1,34 +1,34 @@
 # GitHub Copilot CLI Pre-Push Audit Workflow
 
-This workflow orchestrates an AI-driven adversarial review using the GitHub Copilot CLI (`@github/copilot`). It acts as a strict secondary validation layer (a "second opinion") across both localized logic changes (PR reviews) and full repository inspections.
+This workflow orchestrates an AI-driven adversarial review using the GitHub Copilot CLI (`gh copilot`). It acts as a strict secondary validation layer (a "second opinion") across both localized logic changes (PR reviews) and full repository inspections.
 
 ## Phase 1: Environment Readiness & Authentication
 
 1. **Verify Copilot CLI Presence**:
-   Run `npm list -g @github/copilot`.
-   If missing, install it automatically: `npm i -g @github/copilot`.
+   Run `gh extension list | grep copilot`.
+   If missing, install it via: `gh extension install github/gh-copilot`.
 
 2. **Verify Authentication**:
-   Ensure the CLI is authenticated via `copilot auth`. If the user has not authenticated, pause the agentic execution and prompt them to authorize via the browser endpoint.
+   Ensure the CLI is authenticated via `gh auth status` and test with `gh copilot --version`. If the user has not authenticated, pause the agentic execution and prompt them to authorize (`gh auth login`).
 
 ## Phase 2: Execution Targeting (The Audit Context)
 
 Determine whether this is a localized Feature Branch (Pre-Push PR) review or a whole Codebase Audit.
 
+> **Note**: The `gh copilot` extension does not natively support non-interactive file stream piping. The agent must use `gh copilot explain` or instruct the user to use the Copilot Chat window with the generated prompts.
+
 ### Path A: Pre-Push PR Review
 
 1. Diff the current working branch against the primary target (e.g., `main` or `master`).
-2. **Execute Single-Shot Evaluation Buffer**:
-   ```bash
-   git diff main | copilot "Act as an extremely strict, senior PR reviewer. Review this submitted git diff. Analyze edge cases, logic gaps, unhandled bounds, typescript compliance, and security flaws. Produce a Markdown-formatted table of defects."
-   ```
+2. **Execute Evaluation**:
+   Prompt the user to review the diff in their IDE's Copilot Chat using this prompt:
+   "Act as an extremely strict, senior PR reviewer. Review this submitted git diff. Analyze edge cases, logic gaps, unhandled bounds, typescript compliance, and security flaws. Produce a Markdown-formatted table of defects."
 
 ### Path B: Comprehensive Codebase Review
 
-1. **Execute Single-Shot Codebase Buffer**:
-   ```bash
-   echo "Act as an adversarial security and performance auditor. Perform a comprehensive analysis of all files in this repository. Point out bad architectural couplings, injection vectors, unhandled error flows, and data boundaries that are not explicit. Output as a detailed Markdown report." | copilot
-   ```
+1. **Execute Codebase Evaluation**:
+   Prompt the user to perform the review in their IDE using the Workspace chat context (`@workspace`):
+   "Act as an adversarial security and performance auditor. Perform a comprehensive analysis of all files in this repository. Point out bad architectural couplings, injection vectors, unhandled error flows, and data boundaries that are not explicit. Output as a detailed Markdown report."
 
 ## Phase 3: Journal Archival (Verification Sync)