@codyswann/lisa 2.19.0 → 2.20.0

package/plugins/lisa-harper-fabric/rules/harper-fabric.md

@@ -0,0 +1,51 @@
+# Harper/Fabric Project Rules
+
+These rules apply to Harper/Fabric component apps managed by Lisa.
+
+## Build The Real Thing
+
+- Do not ship client-side workarounds for missing backend behavior. If a change needs a Harper resource, schema update, seed path, or deploy script change, make that change.
+- Do not silently downgrade a feature to a stub, mock, or partial path. Only use a stop-gap when the user explicitly asks for one.
+- Treat deployed Fabric behavior as part of the product. A change is unfinished until the local build and the relevant deployed or smoke path agree.
+
+## TypeScript Is Source
+
+- TypeScript under `src/` is the source of truth for Harper resources, browser modules, shared libraries, and operational scripts.
+- `harper-app/config.yaml`, `harper-app/schema.graphql`, HTML, CSS, docs, and research fixtures are source assets.
+- `harper-app/resources.js` and `harper-app/web/**/*.js` are generated deploy artifacts. Never edit them directly; change the matching TypeScript and run `bun run build`.
+- Deployment, bootstrap, smoke, seed, verify, preview, token, crawl, ingest, and extraction commands must run from compiled JavaScript or generated Harper assets, not stale checked-in JavaScript.
+
+## Harper/Fabric Deploy Surface
+
+- A deployable Harper app must keep `config.yaml`, `schema.graphql`, `resources.js`, and `web/**` at the component root that Fabric packages.
+- Build before symlinking, packaging, or deploying `harper-app/`.
+- Keep runtime secrets out of tracked files. Prefer environment variables or OS keychain helpers; document secret locations without recording secret values.
+- When discovering a Harper/Fabric limitation or workaround, document the symptom, root cause, fix, and tempting broken alternatives in the project runbook.
+
+## Documentation Sync
+
+- Project docs are operational contracts. When commands, schema, deploy shape, data model, seeded-data summary, crawler behavior, credential handling, or UI components change, update the matching project doc in the same change.
+- Harper schema changes must update the conceptual schema docs and any verify paths that assert joins or row counts.
+- Deploy topology, credential rotation, generated-artifact layout, and Fabric workarounds belong in the Fabric runbook.
+- UI component, token, variant, or design-system changes must update the design-system catalog.
+
+## UI Work
+
+- Browser UI must be composed from the project design system. Search the existing design-system catalog and components before adding markup.
+- Add or extend the design-system component first, then consume it from pages.
+- Pages should import UI components through the design-system barrel, not deep component paths.
+- Do not introduce raw colors or ad hoc spacing in UI styles. Use design tokens and update the token docs when adding tokens.
+- Every UI change needs Playwright verification that checks DOM behavior and captures screenshots. Type checks and unit tests are not enough for visual changes.
+
+## Immutable Code
+
+- Prefer immutable data flow: `readonly` types, pure transformations, object/array copies, and explicit returned values.
+- Do not mutate parameters, imported singletons, fixture objects, records, arrays, DOM-derived state, or config objects unless an API requires mutation and the exception is documented locally.
+- Avoid `let`; use `const` and small pure helper functions instead.
+- Avoid `any`, broad casts, and `ts-ignore`. If an external API forces an escape hatch, isolate it behind a typed adapter.
+
+## Verification
+
+- Run `bun run build`, `bun run typecheck`, and the smallest relevant test command before reporting completion.
+- For deploy-affecting changes, also run the project smoke command against the local or deployed Harper endpoint.
+- If a verification command cannot run, report the exact command and blocker.

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/src/harper-fabric/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "lisa-harper-fabric",
+  "version": "1.0.0",
+  "description": "Harper/Fabric-specific rules for TypeScript component apps",
+  "author": { "name": "Cody Swann" },
+  "dependencies": ["lisa-typescript"],
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh" }] }
+    ],
+    "SubagentStart": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh" }] }
+    ]
+  }
+}

package/plugins/src/harper-fabric/hooks/inject-rules.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Reads all .md files from the plugin's rules/ directory and injects them
+# into Claude context at session/subagent start.
+set -euo pipefail
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+RULES_DIR="$ROOT/rules"
+
+[ -d "$RULES_DIR" ] || exit 0
+
+for rule in "$RULES_DIR"/*.md; do
+  [ -f "$rule" ] || continue
+  printf '\n<lisa-harper-fabric-rule path="%s">\n' "$rule"
+  cat "$rule"
+  printf '\n</lisa-harper-fabric-rule>\n'
+done

package/plugins/src/harper-fabric/rules/harper-fabric.md

@@ -0,0 +1,51 @@
+# Harper/Fabric Project Rules
+
+These rules apply to Harper/Fabric component apps managed by Lisa.
+
+## Build The Real Thing
+
+- Do not ship client-side workarounds for missing backend behavior. If a change needs a Harper resource, schema update, seed path, or deploy script change, make that change.
+- Do not silently downgrade a feature to a stub, mock, or partial path. Only use a stop-gap when the user explicitly asks for one.
+- Treat deployed Fabric behavior as part of the product. A change is unfinished until the local build and the relevant deployed or smoke path agree.
+
+## TypeScript Is Source
+
+- TypeScript under `src/` is the source of truth for Harper resources, browser modules, shared libraries, and operational scripts.
+- `harper-app/config.yaml`, `harper-app/schema.graphql`, HTML, CSS, docs, and research fixtures are source assets.
+- `harper-app/resources.js` and `harper-app/web/**/*.js` are generated deploy artifacts. Never edit them directly; change the matching TypeScript and run `bun run build`.
+- Deployment, bootstrap, smoke, seed, verify, preview, token, crawl, ingest, and extraction commands must run from compiled JavaScript or generated Harper assets, not stale checked-in JavaScript.
+
+## Harper/Fabric Deploy Surface
+
+- A deployable Harper app must keep `config.yaml`, `schema.graphql`, `resources.js`, and `web/**` at the component root that Fabric packages.
+- Build before symlinking, packaging, or deploying `harper-app/`.
+- Keep runtime secrets out of tracked files. Prefer environment variables or OS keychain helpers; document secret locations without recording secret values.
+- When discovering a Harper/Fabric limitation or workaround, document the symptom, root cause, fix, and tempting broken alternatives in the project runbook.
+
+## Documentation Sync
+
+- Project docs are operational contracts. When commands, schema, deploy shape, data model, seeded-data summary, crawler behavior, credential handling, or UI components change, update the matching project doc in the same change.
+- Harper schema changes must update the conceptual schema docs and any verify paths that assert joins or row counts.
+- Deploy topology, credential rotation, generated-artifact layout, and Fabric workarounds belong in the Fabric runbook.
+- UI component, token, variant, or design-system changes must update the design-system catalog.
+
+## UI Work
+
+- Browser UI must be composed from the project design system. Search the existing design-system catalog and components before adding markup.
+- Add or extend the design-system component first, then consume it from pages.
+- Pages should import UI components through the design-system barrel, not deep component paths.
+- Do not introduce raw colors or ad hoc spacing in UI styles. Use design tokens and update the token docs when adding tokens.
+- Every UI change needs Playwright verification that checks DOM behavior and captures screenshots. Type checks and unit tests are not enough for visual changes.
+
+## Immutable Code
+
+- Prefer immutable data flow: `readonly` types, pure transformations, object/array copies, and explicit returned values.
+- Do not mutate parameters, imported singletons, fixture objects, records, arrays, DOM-derived state, or config objects unless an API requires mutation and the exception is documented locally.
+- Avoid `let`; use `const` and small pure helper functions instead.
+- Avoid `any`, broad casts, and `ts-ignore`. If an external API forces an escape hatch, isolate it behind a typed adapter.
+
+## Verification
+
+- Run `bun run build`, `bun run typecheck`, and the smallest relevant test command before reporting completion.
+- For deploy-affecting changes, also run the project smoke command against the local or deployed Harper endpoint.
+- If a verification command cannot run, report the exact command and blocker.

package/rails/copy-overwrite/lefthook.yml

@@ -5,7 +5,11 @@ pre-commit:
       glob: '*.rb'
       run: bundle exec rubocop --force-exclusion {staged_files}
     bundler-audit:
-      run: bundle exec bundler-audit check --update
+      # Unset GIT_DIR/GIT_WORK_TREE so `--update`'s internal git pull of the
+      # ruby-advisory-db (~/.local/share/ruby-advisory-db) does not inherit the
+      # repo's git context. Without this, the command fails when the hook runs
+      # inside a git worktree (the inherited GIT_DIR points at the wrong repo).
+      run: env -u GIT_DIR -u GIT_WORK_TREE bundle exec bundler-audit check --update
 
 commit-msg:
   commands:

package/scripts/build-plugins.sh

@@ -34,7 +34,7 @@ node "$ROOT_DIR/scripts/generate-codex-plugin-artifacts.mjs" "$BASE_OUT" "$VERSI
 echo "Built plugins/lisa (v$VERSION)"
 
 # Build stack-specific plugins (NO base copy)
-STACKS=(typescript expo nestjs cdk rails)
+STACKS=(typescript expo nestjs cdk harper-fabric rails)
 for stack in "${STACKS[@]}"; do
   STACK_SRC="$SRC_DIR/$stack"
   if [ ! -d "$STACK_SRC" ]; then

package/scripts/copy-codex-scripts.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Copy shell hook scripts next to the compiled Codex hook installer.
+ *
+ * TypeScript compilation emits `dist/codex/hooks-installer.js`, whose runtime
+ * resolver looks for scripts in `dist/codex/scripts/`. The source scripts are
+ * plain shell files, so tsc does not copy them.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+const sourceDir = path.join(repoRoot, "src", "codex", "scripts");
+const destDir = path.join(repoRoot, "dist", "codex", "scripts");
+
+fs.rmSync(destDir, { recursive: true, force: true });
+fs.mkdirSync(destDir, { recursive: true });
+
+for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+  if (!entry.isFile()) {
+    continue;
+  }
+
+  const sourcePath = path.join(sourceDir, entry.name);
+  const destPath = path.join(destDir, entry.name);
+  fs.copyFileSync(sourcePath, destPath);
+  fs.chmodSync(destPath, 0o755);
+}

package/scripts/generate-codex-plugin-artifacts.mjs

@@ -267,6 +267,21 @@ function metadataFor(pluginName) {
       keywords: ["aws", "cdk", "infrastructure"],
       defaultPrompt: ["Review this CDK change"],
     },
+    "lisa-harper-fabric": {
+      displayName: "Lisa Harper/Fabric",
+      description:
+        "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
+      shortDescription: "Harper/Fabric workflow guidance",
+      longDescription:
+        "Lisa rules for Harper/Fabric deploy surfaces, generated JavaScript artifacts, operational docs, Playwright UI verification, and immutable TypeScript.",
+      category: "Coding",
+      capabilities: ["Interactive", "Write"],
+      keywords: ["harper", "fabric", "typescript", "playwright"],
+      defaultPrompt: [
+        "Review this Harper/Fabric change",
+        "Verify this Harper/Fabric deployment path",
+      ],
+    },
     "lisa-rails": {
       displayName: "Lisa Rails",
       description:

package/scripts/install-claude-plugins.sh

@@ -117,7 +117,7 @@ if command -v jq >/dev/null 2>&1; then
     | jq -r '.[] | select(.name == "lisa" and .source != "github") | .source' 2>/dev/null \
     | head -n 1)
   if [ -n "${STALE_LISA_SOURCE:-}" ]; then
-    for stale_plugin in "lisa@lisa" "lisa-typescript@lisa" "lisa-expo@lisa" "lisa-nestjs@lisa" "lisa-cdk@lisa" "lisa-rails@lisa"; do
+    for stale_plugin in "lisa@lisa" "lisa-typescript@lisa" "lisa-expo@lisa" "lisa-nestjs@lisa" "lisa-cdk@lisa" "lisa-harper-fabric@lisa" "lisa-rails@lisa"; do
       claude plugin uninstall "$stale_plugin" --scope project </dev/null >/dev/null 2>&1 || true
     done
     claude plugin marketplace remove lisa </dev/null >/dev/null 2>&1 || true
@@ -140,7 +140,7 @@ fi
 # installed lisa-* plugins so they get re-resolved as remote. Worktrees under
 # .claude/worktrees/ have their own per-cwd plugin install state and are
 # healed in the same pass. A marker file gates one-time execution per cwd.
-LISA_PLUGINS=("lisa@lisa" "lisa-typescript@lisa" "lisa-expo@lisa" "lisa-nestjs@lisa" "lisa-cdk@lisa" "lisa-rails@lisa")
+LISA_PLUGINS=("lisa@lisa" "lisa-typescript@lisa" "lisa-expo@lisa" "lisa-nestjs@lisa" "lisa-cdk@lisa" "lisa-harper-fabric@lisa" "lisa-rails@lisa")
 HEAL_V2_MARKER_NAME=".lisa-marketplace-heal-v2"
 
 heal_local_classification() {
@@ -210,7 +210,7 @@ claude plugin install "lisa@lisa" --scope project </dev/null 2>&1 || true
 # Detect which stack plugin to install from .claude/settings.json
 LISA_STACK=""
 if [ -f "$SETTINGS_FILE" ] && command -v jq >/dev/null 2>&1; then
-  for stack in expo nestjs cdk rails; do
+  for stack in expo nestjs cdk harper-fabric rails; do
     if jq -e "(.enabledPlugins // {}) | has(\"lisa-${stack}@lisa\")" "$SETTINGS_FILE" >/dev/null 2>&1; then
       LISA_STACK="$stack"
       break
@@ -232,7 +232,7 @@ if [ -n "$LISA_STACK" ]; then
 fi
 
 # Uninstall old monolithic plugins during migration
-for old_plugin in "lisa-typescript@lisa" "lisa-expo@lisa" "lisa-nestjs@lisa" "lisa-cdk@lisa" "lisa-rails@lisa"; do
+for old_plugin in "lisa-typescript@lisa" "lisa-expo@lisa" "lisa-nestjs@lisa" "lisa-cdk@lisa" "lisa-harper-fabric@lisa" "lisa-rails@lisa"; do
   # Skip if it's the same as what we just installed
   case "$LISA_STACK" in
     "") [ "$old_plugin" = "lisa-typescript@lisa" ] && continue ;;
@@ -255,7 +255,7 @@ for plugin in \
 done
 
 # Install stack-specific third-party plugins
-if [ "$LISA_STACK" = "expo" ]; then
+if [ "$LISA_STACK" = "expo" ] || [ "$LISA_STACK" = "harper-fabric" ]; then
   for plugin in \
     "playwright@claude-plugins-official" \
     "posthog@claude-plugins-official"; do

package/tsconfig/harper-fabric.json

@@ -0,0 +1,20 @@
+{
+  "extends": "./typescript.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM"],
+    "rootDir": ".",
+    "outDir": "dist",
+    "resolveJsonModule": true,
+    "allowJs": false,
+    "skipLibCheck": true,
+    "types": ["node", "vitest"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "exclude": [
+    "dist",
+    "coverage",
+    "node_modules",
+    "harper-app/resources.js",
+    "harper-app/web/**/*.js"
+  ]
+}