@opensassi/opencode 0.1.0

package/skills/npm-optimizer/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: npm-optimizer
+description: Port an existing npm package to a C++ native addon — preserve 100% test compatibility while significantly improving performance through profiling-driven architectural iteration.
+---
+
+# Skill: npm-optimizer
+
+## Persona
+
+Senior systems engineer specializing in Node.js native addon development and performance optimization. Strong background in C++, V8 internals, perf profiling, and the npm build pipeline (node-gyp, N-API).
+
+## On Activation
+
+1. Check that a target npm package name is available in context. If not, prompt.
+2. Run `show-state` to summarize current progress through the `execute` pipeline.
+3. List which phases of `execute` have been completed and which are pending.
+
+## Commands
+
+### `execute`
+
+Run the full port pipeline. Each phase must complete before the next begins. The agent pauses after each phase, reports results, and waits for acknowledgment before proceeding.
+
+---
+
+**Phase 1 — Spec & Discovery**
+
+Goal: Understand the original package's full surface area before writing any code.
+
+1.1. Clone the target package into `external/<name>/`:
+     ```
+     git clone --depth 1 <repo-url> external/<name>
+     ```
+
+1.2. Copy the original test suite to `test/orig/`. Run it against the original to
+     establish a passing baseline. These tests must never be modified.
+
+1.3. Analyze the original source tree. For each source file, use the system-design
+     skill's spec workflow to produce a spec document. Group related files into
+     sub-modules. Output tree at:
+     ```
+     spec/original/
+     ├── <sub-module-1>/README.md
+     ├── <sub-module-2>/README.md
+     └── technical-specification.md    (root overview + data flow)
+     ```
+
+1.4. From the spec tree, extract:
+     - Full API surface: every exported function, its signature, and behavior.
+     - Edge cases: undefined properties, NaN, toJSON, circular refs, prototype chain.
+     - Data flow: how inputs map to outputs.
+
+1.5. **Validate the ceiling** — Before designing the C++ architecture, build the
+     cheapest possible pass-through: a minimal addon that takes a string blob,
+     copies it, and returns it. Measure its ops/sec via `npm run benchmark`.
+     This is the **upper bound** for any approach that uses this N-API profile
+     (one crossing in, one out). If this doesn't exceed the original's speed,
+     the entire approach is dead — reconsider at the JS/N-API design level.
+
+1.6. Design the C++ addon architecture:
+     - Which functions go native vs stay in JS wrapper.
+     - N-API boundary strategy (minimize crossings per call).
+     - Build pipeline (binding.gyp, node-addon-api, dependencies).
+
+1.7. Generate implementation spec tree at `spec/implementation/` mirroring the
+     original's structure, with cross-reference mappings.
+
+---
+
+**Phase 2 — Naive Implementation**
+
+Goal: Build the simplest C++ addon that passes 100% of `test/orig/*.js`.
+
+2.1. Scaffold project: `package.json`, `binding.gyp`, `src/`, `index.js`
+2.2. Implement the C++ module with the direct approach
+     (e.g., traverse values through N-API, build string in C++).
+2.3. Run `test/orig/` tests. Fix until all pass.
+2.4. Establish baseline benchmark: `npm run benchmark` comparing against original JS.
+
+---
+
+**Phase 3 — Profile & Classify**
+
+Goal: Identify where time is actually going.
+
+3.1. Create `prof-harness.js` — tight loop exercising the main export.
+3.2. `perf record -F 199 --call-graph fp -o perf/baseline.profile.data node prof-harness.js`
+3.3. `perf report -i perf/baseline.profile.data --stdio -s overhead,symbol,dso`
+3.4. Classify samples into three tiers:
+     - **Tier 1 — Infrastructure**: V8 internals, N-API boundary, allocator.
+     - **Tier 2 — Our C++ logic**: string building, type dispatch, sorting.
+     - **Tier 3 — The original's work**: if we're still calling it.
+3.5. **Decision**: If Tier 1 > 30% of samples, mark as **architectural bottleneck**
+     and proceed to Phase 4A (pivot). Otherwise proceed to Phase 4B (micro-optimize).
+
+---
+
+**Phase 4A — Architectural Pivot**
+
+Goal: Change the approach when the current architecture hits a fundamental ceiling.
+
+4A.1. Identify the specific architectural cost (e.g., "200+ N-API crossings per call").
+4A.2. Design an alternative approach that eliminates this cost. Examples:
+      - "Let JSON.stringify do the work, then key-sort the blob in C++"
+      - "Batch N-API calls" / "Use raw V8 API instead of N-API"
+      - "Pre-allocate and reuse buffers across calls"
+4A.3. **Validate the hypothesis** — before implementing the full approach, build
+      the cheapest functional approximation (pass-through, stub). Measure it.
+      If the ceiling doesn't leave headroom over the original, reject this approach
+      and go back to 4A.2.
+4A.4. If validated: implement the full pivot approach. Run tests (100% pass).
+4A.5. Run benchmark. If target met, proceed to Phase 5.
+      If not, return to Phase 3 with new profile data.
+
+---
+
+**Phase 4B — Micro-Optimize**
+
+Goal: Attack specific C++ hotspots identified in Phase 3.
+
+4B.1. For each Tier-2 function, sorted by self% descending:
+      - Read the source code of the function.
+      - Identify the specific operation consuming time
+        (e.g., `std::ostringstream`, repeated allocation, branch-heavy loop).
+      - Apply one targeted fix.
+      - Rebuild, run tests, benchmark.
+      - If gain >= 5%: keep, move to next function.
+      - If gain < 5%: revert, try next hypothesis for this function.
+4B.2. **Three strikes rule**: if three consecutive fixes at this function
+      each yield <5%, stop micro-optimizing. Re-run Phase 3 and check
+      Tier 1 fraction. If it grew, proceed to Phase 4A.
+4B.3. When all Tier-2 functions are exhausted: re-run Phase 3.
+      If Tier 1 is now dominant, proceed to Phase 4A.
+
+---
+
+**Phase 5 — Compatibility Shim & Documentation**
+
+Goal: Handle edge cases where the implementation differs from the original.
+
+5.1. Compare output of original vs implementation for:
+      - All `test/orig/` cases (must pass).
+      - Edge cases: function-valued properties, undefined, toJSON,
+        prototype-chain access, Symbol-keyed properties.
+5.2. For any behavioral difference: add JS wrapper logic in `index.js`
+      (e.g., preprocess step for function→{} conversion).
+      Document the difference in `spec/cross-reference.md` with rationale.
+5.3. Generate `test/new/` tests covering implementation-specific behavior.
+5.4. Update `spec/cross-reference.md` with final benchmark deltas.
+
+---
+
+**Phase 6 — Report**
+
+Goal: Produce the final deliverable.
+
+6.1. Generate comparison table:
+     ```
+     | Implementation          | Ops/sec | Relative |
+     |-------------------------|---------|----------|
+     | Original JS             | X       | 1.0x     |
+     | C++ addon               | Y       | Y/X      |
+     | Pass-through (ceiling)  | Z       | Z/X      |
+     ```
+6.2. Archive final profile: `cp perf/baseline.profile.data perf/baseline/profiles/final.profile.data`
+6.3. Print the full report inline: benchmark numbers, profile summary, spec cross-reference path,
+      and a list of known behavioral differences (if any).
+
+### `show-state`
+
+Output the current status of the `execute` pipeline:
+
+```
+Phase 1 (Spec): COMPLETE — spec tree at spec/original/
+Phase 2 (Naive): IN PROGRESS — 43/49 tests passing
+Phase 3 (Profile): PENDING
+Phase 4 (Optimize): PENDING
+Phase 5 (Shim): PENDING
+Phase 6 (Report): PENDING
+
+Baseline benchmark: 8,037 ops/sec (original: 33,199)
+Ceiling (pass-through): 104,866 ops/sec
+```
+
+## Design Principles
+
+- **Tests are the contract.** `test/orig/` is never modified.
+  `test/new/` covers implementation-specific behavior.
+
+- **Profile before optimizing.** Always run `perf record` / `perf report` before
+  any change. The data decides, not intuition.
+
+- **Classify bottlenecks first.** If >30% of samples are in infrastructure
+  (V8 internals, N-API boundary, allocator), the fix is architectural, not micro.
+
+- **Three strikes rule.** If three consecutive micro-optimizations yield <5% each,
+  stop. The bottleneck is architectural. Pivot.
+
+- **Validate the pivot cheaply.** Before building a new approach, build the
+  cheapest functional version (pass-through, stub). If the ceiling doesn't leave
+  headroom for the real work, reject the approach immediately.
+
+- **Fail fast on integration.** When a library integration crashes, investigate
+  just enough to understand WHY (one root cause), document it, and pivot.
+  Search for existing npm bindings as reference before deep debugging.
+
+- **Trace algorithms on paper.** When recursive logic crashes with no clear cause,
+  walk through it manually with the simplest reproducer. Do not printf-debug
+  recursive algorithms — the bug is almost always in the depth-tracking or
+  separator-skipping logic.
+
+- **Spec first, implement second.** Before writing any C++, generate the full spec
+  tree of the original package. The implementation spec mirrors this. The
+  cross-reference is the validation contract.
+
+- **Know when to stop.** When the bottleneck moves to a component you're deliberately
+  leveraging (e.g., V8's JSON.stringify), further optimization within your code
+  gives diminishing returns. Ship it.

package/skills/opensassi/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: opensassi
+description: Bootstrap a new project environment — detect OS, install toolchain (git, Node.js via nvm/LTS), clone FlameGraph, set up project infrastructure
+---
+
+# Skill: opensassi
+
+## Persona
+
+Senior DevOps engineer specializing in cross-platform development environment provisioning, with deep expertise in nvm, package managers (apt/dnf/yum/pacman/brew/choco), and build toolchain setup.
+
+## On Activation
+
+1. Show the skills-index (from `skills-index.json` or by running `npx @opensassi/opencode opensassi --print-index`)
+2. Run `init check` to report current environment status (OS, Node.js, git, FlameGraph, npm deps)
+3. Show available commands
+
+To load a sub-skill (e.g., system-design, git, profiler), the agent should run:
+```
+npx @opensassi/opencode <skill-name>
+```
+and read the output as the skill's full instructions.
+
+## Dependencies
+
+- `bash` or `powershell` (for bootstrap scripts — zero other deps)
+- `git` (installed by bootstrap if missing)
+- The `@opensassi/opencode` npm package (scripts resolve via `npx @opensassi/opencode run --skill opensassi <name>`)
+
+## Commands
+
+### `init`
+
+Execute companion scripts from the `@opensassi/opencode` package. If a script is missing or a platform installer does not exist, report the gap and continue; do not generate files.
+
+1. `npx @opensassi/opencode run --skill opensassi env-check.sh` (or `env-check.ps1` on Windows) — bootstrap git + Node.js LTS (creates `.nvmrc` if missing)
+2. `init install` — run existing platform installer, or report if none found
+3. `init flamegraph` — clone FlameGraph v1.0
+4. `npx @opensassi/opencode run --skill opensassi install-npm-deps.sh` — `npm install`
+5. `npx @opensassi/opencode run --skill opensassi ensure-gitignore.sh` — append common patterns
+
+### `init install`
+
+Install the development environment toolchain.
+
+**Flow:**
+
+1. **Detect environment** — run `npx @opensassi/opencode run --skill opensassi env-check.sh` (Linux/macOS/WSL/Git Bash) or fall back to `env-check.ps1` (Windows native). Both output structured JSON.
+2. **Check for existing installer** — look for `npx @opensassi/opencode run install.sh` for platform-specific installers from the package's `scripts/install/` directory
+3. **If installer exists** — run it (installs: cmake, nasm, gdb, ripgrep, perf, htop, etc.)
+4. **If installer NOT found**:
+   a. Report: "No installer found for this platform"
+   b. Continue — env-check already installed git + Node.js, which is sufficient for the project to function
+
+### `init flamegraph`
+
+Clone Brendan Gregg's FlameGraph at pinned tag `v1.0` to `scripts/FlameGraph/`:
+- If `scripts/FlameGraph/` does not exist: `git clone --depth=1 --branch v1.0`
+- If it exists: `git fetch --tags --depth=1 && git checkout v1.0`
+
+### `init check`
+
+Run `npx @opensassi/opencode run --skill opensassi env-check.sh` (or `env-check.ps1`) and verify:
+- Node.js version (LTS or later)
+- git availability
+- FlameGraph presence at `scripts/FlameGraph/`
+- npm deps installed (`node_modules/` exists)
+- `.gitignore` has common patterns
+
+## Design Principles
+
+- **No circular dependencies on Node.js** — Bootstrap scripts use only bash or PowerShell. Node.js is installed BY the bootstrap.
+- **nvm is additive, not destructive** — `nvm install --lts` installs alongside existing Node versions. `nvm use --lts` scopes to the current shell only. System default node is never touched.
+- **`.nvmrc` for the project** — Written with `--lts` so `nvm use` auto-selects when entering the project directory.
+- **FlameGraph pinned at v1.0** — Tag is stable; pinned clones are idempotent.
+- **`install.ps1` is WSL-only** — Not modified by this skill. Windows-native installer is a future extension.
+- **env-check scripts output JSON** — Structured `{os, distro, version, codename, pkg_manager, shell, is_wsl, arch, node_version, nvm_version, git_version}` for AI agent consumption.

package/skills/opensassi/scripts/ensure-gitignore.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# ensure-gitignore.sh — Add common .gitignore patterns if missing.
+# Usage: bash ensure-gitignore.sh
+
+set -euo pipefail
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || (cd "$(dirname "$0")/../../.." && pwd))"
+GITIGNORE="$PROJECT_ROOT/.gitignore"
+
+PATTERNS=(
+    "# Build directories"
+    "/build*/"
+    "/bin/"
+    "/lib/"
+    "/install/"
+
+    "# IDE"
+    ".vscode/"
+    ".idea/"
+    "*.swp"
+    "*.swo"
+
+    "# Dependencies"
+    "node_modules/"
+
+    "# Generated artifacts"
+    ".artifacts/"
+    "src/**/.artifacts/"
+
+    "# FlameGraph (cloned by opensassi skill at v1.0)"
+    "scripts/FlameGraph/"
+
+    "# Browser automation"
+    ".playwright-mcp/"
+
+    "# Profiling and performance data"
+    ".profiler/"
+
+    "# Sessions"
+    "sessions/"
+    "!sessions/export-session.sh"
+    "!sessions/.gitkeep"
+    "!sessions/daily/.gitkeep"
+
+    "# Performance experiments"
+    "perf/experiments/"
+    "perf/baseline/"
+
+    "# Test data"
+    "test/data/"
+
+    "# CTest temporary files"
+    "Testing/"
+
+    "# External project clones"
+    "/external/"
+
+    "# OS files"
+    ".DS_Store"
+    "Thumbs.db"
+
+    "# Core dumps"
+    "core"
+)
+
+ensure_pattern() {
+    local pattern="$1"
+    # Skip comment lines
+    if [[ "$pattern" == \#* ]]; then
+        return 0
+    fi
+    # Check for existing pattern with optional leading /
+    local alt="${pattern#!}"
+    [[ "$pattern" == \!* ]] && alt="!/${alt#/}" || alt="/${alt#/}"
+    if grep -qxF "$pattern" "$GITIGNORE" 2>/dev/null || grep -qxF "$alt" "$GITIGNORE" 2>/dev/null; then
+        return 0
+    fi
+    echo "$pattern" >> "$GITIGNORE"
+    echo "  [added] $pattern"
+}
+
+# Ensure file exists
+touch "$GITIGNORE"
+
+echo "[INFO] Ensuring .gitignore patterns..."
+for p in "${PATTERNS[@]}"; do
+    ensure_pattern "$p"
+done
+echo "[INFO] .gitignore is up to date"

package/skills/opensassi/scripts/env-check.ps1

@@ -0,0 +1,139 @@
+# env-check.ps1 — Bootstrap environment detection for opencode opensassi skill (Windows native).
+# Detects OS, ensures git, installs Node.js LTS via nvm-windows if needed.
+# Outputs JSON to stdout: {os, distro, version, codename, pkg_manager, shell,
+#                          is_wsl, arch, node_version, nvm_version, git_version}
+#
+# Usage: powershell -ExecutionPolicy Bypass -File env-check.ps1
+
+$ErrorActionPreference = "Stop"
+
+# --- OS Detection ---
+$os = "win32"
+$distro = "windows"
+$version = ""
+$codename = ""
+$arch = [Environment]::GetEnvironmentVariable("PROCESSOR_ARCHITECTURE")
+if ($arch -match "AMD64|x86_64") { $arch = "x64" }
+elseif ($arch -match "ARM64") { $arch = "arm64" }
+$shell = "powershell"
+$is_wsl = $false
+
+# Detect package manager
+$pkg_manager = ""
+if (Get-Command winget -ErrorAction SilentlyContinue) { $pkg_manager = "winget" }
+elseif (Get-Command choco -ErrorAction SilentlyContinue) { $pkg_manager = "choco" }
+elseif (Get-Command scoop -ErrorAction SilentlyContinue) { $pkg_manager = "scoop" }
+
+# --- Ensure git ---
+$git_version = ""
+try {
+    $git_out = & git --version 2>$null
+    if ($git_out) {
+        $git_version = ($git_out -replace 'git version ', '').Trim()
+    }
+} catch {
+    Write-Host "[INFO] git not found. Installing via winget..." -ForegroundColor Yellow
+    if ($pkg_manager -eq "winget") {
+        & winget install Git.Git --silent --accept-package-agreements 2>$null
+        # Refresh PATH so git is available
+        $env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")
+        $git_out = & git --version 2>$null
+        if ($git_out) { $git_version = ($git_out -replace 'git version ', '').Trim() }
+    } else {
+        Write-Host "[WARN] Cannot install git automatically. Install from https://git-scm.com/" -ForegroundColor Red
+    }
+}
+
+# --- Ensure Node.js (LTS via nvm-windows) ---
+$node_version = ""
+$nvm_version = ""
+
+function Setup-Node {
+    # Check if node is already at LTS or later
+    try {
+        $current = & node --version 2>$null
+        if ($current) {
+            $current = $current -replace '^v', ''
+            $major = ($current -split '\.')[0]
+            if ($major -ge 18) {
+                $script:node_version = $current
+                Write-Host "[INFO] Node.js v$node_version already available" -ForegroundColor Green
+                return
+            }
+        }
+    } catch {
+        # node not found, continue
+    }
+
+    # Check for nvm-windows
+    $nvm_path = Get-Command nvm -ErrorAction SilentlyContinue
+    if (-not $nvm_path) {
+        Write-Host "[INFO] nvm-windows not found. Installing via winget..." -ForegroundColor Yellow
+        try {
+            if ($pkg_manager -eq "winget") {
+                & winget install CoreyButler.NVMforWindows --silent --accept-package-agreements 2>$null
+                # nvm-windows adds to PATH; need a new shell or reload
+                $env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")
+                # nvm-windows may need a refresh
+                $env:NVM_HOME = "$env:USERPROFILE\AppData\Roaming\nvm"
+                $env:NVM_SYMLINK = "$env:ProgramFiles\nodejs"
+                $env:Path = "$env:NVM_HOME;$env:NVM_SYMLINK;$env:Path"
+            } else {
+                Write-Host "[WARN] Cannot install nvm-windows automatically. Install from:" -ForegroundColor Red
+                Write-Host "  https://github.com/coreybutler/nvm-windows/releases" -ForegroundColor Red
+                return
+            }
+        } catch {
+            Write-Host "[ERROR] Failed to install nvm-windows." -ForegroundColor Red
+            return
+        }
+    }
+
+    # Verify nvm is available
+    try {
+        $nvm_ver = & nvm version 2>$null
+        if ($nvm_ver) {
+            $script:nvm_version = $nvm_ver.Trim()
+            Write-Host "[INFO] nvm-windows v$nvm_version found" -ForegroundColor Green
+        }
+    } catch {
+        Write-Host "[WARN] nvm command not available after install. Restart terminal and retry." -ForegroundColor Red
+        return
+    }
+
+    # Install LTS node
+    Write-Host "[INFO] Installing latest Node.js LTS via nvm-windows..." -ForegroundColor Yellow
+    try {
+        & nvm install lts 2>$null
+        & nvm use lts 2>$null
+        # Write .nvmrc for the project
+        $project_root = if (Test-Path ".git") { (Get-Location).Path } else { "." }
+        "--lts" | Out-File -FilePath "$project_root\.nvmrc" -Encoding utf8 -Force
+        $node_ver = & node --version 2>$null
+        if ($node_ver) {
+            $script:node_version = ($node_ver -replace '^v', '').Trim()
+            Write-Host "[INFO] Node.js v$node_version (LTS) ready via nvm-windows" -ForegroundColor Green
+        }
+    } catch {
+        Write-Host "[ERROR] Failed to install Node.js LTS." -ForegroundColor Red
+    }
+}
+
+Setup-Node
+
+# --- Output JSON ---
+$json = @{
+    os           = $os
+    distro       = $distro
+    version      = $version
+    codename     = $codename
+    pkg_manager  = $pkg_manager
+    shell        = $shell
+    is_wsl       = $is_wsl
+    arch         = $arch
+    node_version = $node_version
+    nvm_version  = $nvm_version
+    git_version  = $git_version
+}
+
+Write-Output ($json | ConvertTo-Json -Compress)