@codyswann/lisa 2.219.0 → 2.220.0

package/rails/create-only/.github/workflows/ci.yml

@@ -11,7 +11,19 @@ on:
 jobs:
   quality:
     name: Quality Checks
+    # quality-rails.yml declares checks:write + pull-requests:write. A reusable
+    # workflow can only use permissions the caller grants, so on repos whose
+    # default GITHUB_TOKEN is read-only this block is required — without it the
+    # called workflow fails at startup (startup_failure) and required checks
+    # never report.
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
     uses: CodySwannGT/lisa/.github/workflows/quality-rails.yml@main
+    # Rails projects default to PostgreSQL. For a MySQL app, uncomment:
+    # with:
+    #   database_type: 'mysql'
     secrets:
       GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}
       FOSSA_API_KEY: ${{ secrets.FOSSA_API_KEY }}

package/scripts/check-learnings-budget.ts

@@ -0,0 +1,219 @@
+/** CI gate for the canonical project learnings document and its hard budgets. */
+import { constants, existsSync } from "node:fs";
+import { open } from "node:fs/promises";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import type * as LearningsModule from "@codyswann/lisa/learnings";
+
+type LearningsCheckerModule = Pick<
+  typeof LearningsModule,
+  | "LEARNINGS_CONTRACT"
+  | "estimateLearningTokens"
+  | "parseLearningsFile"
+  | "renderLearningsFile"
+  | "validateLearningEntry"
+>;
+
+const DEFAULT_LEARNINGS_FILE = path.resolve(
+  import.meta.dir,
+  "..",
+  "all",
+  "create-only",
+  ".claude",
+  "rules",
+  "PROJECT_LEARNINGS.md"
+);
+
+/** Run the package-facing checker with zero or one explicit file path. */
+async function main(): Promise<void> {
+  const arguments_ = process.argv.slice(2);
+  if (arguments_.length > 1) {
+    fail("Usage: bun run check:learnings-budget -- [PROJECT_LEARNINGS.md]");
+  }
+
+  const file =
+    arguments_.length === 0
+      ? DEFAULT_LEARNINGS_FILE
+      : path.resolve(process.cwd(), arguments_[0] as string);
+
+  try {
+    const {
+      LEARNINGS_CONTRACT,
+      estimateLearningTokens,
+      parseLearningsFile,
+      renderLearningsFile,
+      validateLearningEntry,
+    } = await loadLearningsModule();
+    const content = await readBoundedRegularFile(
+      file,
+      LEARNINGS_CONTRACT.maxTokens
+    );
+    const measuredTokens = estimateLearningTokens(content);
+    if (measuredTokens > LEARNINGS_CONTRACT.maxTokens) {
+      throw new Error(
+        `maxTokens exceeded: measured ${measuredTokens}, allowed ${LEARNINGS_CONTRACT.maxTokens}`
+      );
+    }
+
+    const entries = parseLearningsFile(content);
+    for (const entry of entries) {
+      validateLearningEntry(entry);
+    }
+    if (renderLearningsFile(entries) !== content) {
+      throw new Error("non-canonical project learnings format");
+    }
+
+    console.log(
+      `${formatDiagnosticPath(file)}: learnings budget passed (${entries.length}/${LEARNINGS_CONTRACT.maxEntries} entries, ${measuredTokens}/${LEARNINGS_CONTRACT.maxTokens} maxTokens)`
+    );
+  } catch (error) {
+    fail(`${formatDiagnosticPath(file)}: ${formatErrorDetail(error)}`);
+  }
+}
+
+/**
+ * Render a caught failure without allowing filesystem paths or control bytes
+ * embedded in an Error message to forge additional terminal/CI output.
+ * @param error - Unknown thrown failure
+ * @returns Stable, single-line diagnostic detail
+ */
+function formatErrorDetail(error: unknown): string {
+  if (error !== null && typeof error === "object") {
+    const code = readOwnString(error, "code");
+    if (code !== undefined && /^[A-Z][A-Z0-9_]*$/u.test(code)) {
+      const syscall = readOwnString(error, "syscall");
+      return syscall === undefined
+        ? `filesystem error ${code}`
+        : `filesystem error ${code} during ${escapeDiagnosticText(syscall)}`;
+    }
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return escapeDiagnosticText(message);
+}
+
+/** Read one inert own string property without invoking an accessor. */
+function readOwnString(candidate: object, key: string): string | undefined {
+  const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+  return descriptor !== undefined &&
+    "value" in descriptor &&
+    typeof descriptor.value === "string"
+    ? descriptor.value
+    : undefined;
+}
+
+/** Escape terminal controls while retaining ordinary diagnostic wording. */
+function escapeDiagnosticText(value: string): string {
+  const jsonBody = JSON.stringify(value).slice(1, -1);
+  return jsonBody.replace(
+    /[\u007F-\u009F\u2028\u2029]/gu,
+    character => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`
+  );
+}
+
+/** Quote one path after applying terminal-safe JSON-style escaping. */
+function formatDiagnosticPath(file: string): string {
+  return `"${escapeDiagnosticText(file)}"`;
+}
+
+/**
+ * Read at most one byte beyond the hard budget from one verified regular-file
+ * handle. Non-blocking open prevents a FIFO path from stalling the CI gate.
+ * @param file - Absolute candidate learnings path
+ * @param maximumBytes - Shared executable maxTokens byte ceiling
+ * @returns Strictly decoded UTF-8 content within the byte ceiling
+ */
+async function readBoundedRegularFile(
+  file: string,
+  maximumBytes: number
+): Promise<string> {
+  const handle = await open(file, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile()) {
+      throw new Error("unsafe input: expected a regular file");
+    }
+    if (before.size > BigInt(maximumBytes)) {
+      throw new Error(
+        `maxTokens exceeded: measured ${before.size}, allowed ${maximumBytes}`
+      );
+    }
+
+    const buffer = Buffer.allocUnsafe(maximumBytes + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const result = await handle.read(
+        buffer,
+        bytesRead,
+        buffer.length - bytesRead,
+        null
+      );
+      if (result.bytesRead === 0) {
+        break;
+      }
+      bytesRead += result.bytesRead;
+    }
+    if (bytesRead > maximumBytes) {
+      throw new Error(
+        `maxTokens exceeded: measured at least ${bytesRead}, allowed ${maximumBytes}`
+      );
+    }
+
+    const after = await handle.stat({ bigint: true });
+    if (
+      after.dev !== before.dev ||
+      after.ino !== before.ino ||
+      after.size !== before.size ||
+      after.mtimeNs !== before.mtimeNs ||
+      after.ctimeNs !== before.ctimeNs
+    ) {
+      throw new Error("unsafe input: file changed during bounded read");
+    }
+    return new TextDecoder("utf-8", { fatal: true }).decode(
+      buffer.subarray(0, bytesRead)
+    );
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Load the executable contract from current source in a checkout or compiled
+ * output in an npm package. The `.js` source specifier keeps Bun development
+ * runs aligned with TypeScript's NodeNext resolution while publishing no
+ * runtime dependency on the excluded `src` tree.
+ * @returns Canonical executable learnings module
+ */
+async function loadLearningsModule(): Promise<LearningsCheckerModule> {
+  const packageRoot = path.resolve(import.meta.dir, "..");
+  const sourceTypescript = path.join(
+    packageRoot,
+    "src",
+    "core",
+    "learnings.ts"
+  );
+  const runtimeRoot = path.join(
+    packageRoot,
+    existsSync(sourceTypescript) ? "src" : "dist",
+    "core"
+  );
+  const [contract, document, entry] = await Promise.all([
+    import(pathToFileURL(path.join(runtimeRoot, "learnings-contract.js")).href),
+    import(pathToFileURL(path.join(runtimeRoot, "learnings-document.js")).href),
+    import(pathToFileURL(path.join(runtimeRoot, "learnings-entry.js")).href),
+  ]);
+  return {
+    LEARNINGS_CONTRACT: contract.LEARNINGS_CONTRACT,
+    estimateLearningTokens: contract.estimateLearningTokens,
+    parseLearningsFile: document.parseLearningsFile,
+    renderLearningsFile: document.renderLearningsFile,
+    validateLearningEntry: entry.validateLearningEntry,
+  } as LearningsCheckerModule;
+}
+
+/** Print one deterministic failure diagnostic and exit non-zero. */
+function fail(message: string): never {
+  console.error(`check:learnings-budget: ${message}`);
+  process.exit(1);
+}
+
+await main();

package/typescript/copy-contents/.husky/pre-commit

@@ -51,7 +51,10 @@ if command -v gitleaks >/dev/null 2>&1; then
   GITLEAKS_IGNORE_ARGS=""
   GITLEAKS_COMBINED_IGNORE=""
   if [ -f ".gitleaksignore.local" ]; then
-    GITLEAKS_COMBINED_IGNORE="$(mktemp)"
+    # Explicit template with a trailing X run keeps this portable: BSD/macOS
+    # `mktemp` requires a template argument (bare `mktemp` errors), while GNU
+    # `mktemp` accepts it too.
+    GITLEAKS_COMBINED_IGNORE="$(mktemp "${TMPDIR:-/tmp}/gitleaks-ignore.XXXXXXXX")"
     if [ -f ".gitleaksignore" ]; then
       cat .gitleaksignore > "$GITLEAKS_COMBINED_IGNORE"
       printf '\n' >> "$GITLEAKS_COMBINED_IGNORE"

package/typescript/copy-overwrite/audit.ignore.config.json

@@ -147,11 +147,6 @@
       "id": "GHSA-q3j6-qgpj-74h6",
       "package": "fast-uri",
       "reason": "Path traversal via percent-encoded dot segments in fast-uri parser. Reachable transitively via eslint > @eslint/eslintrc > ajv > fast-uri and (in CDK projects) via aws-cdk-lib's bundled JSON Schema validator. aws-cdk-lib is invoked only at build/synth/deploy time \u2014 its ajv usage validates CloudFormation/CDK schemas authored by the developer, not attacker-controlled URIs. No runtime/production code path passes attacker-controlled URIs through ajv schema validation that relies on fast-uri parsing."
-    },
-    {
-      "id": "GHSA-gv7w-rqvm-qjhr",
-      "package": "esbuild",
-      "reason": "Missing binary integrity verification in esbuild's Deno install module enables RCE via a malicious NPM_CONFIG_REGISTRY. esbuild is dev/build-time only \u2014 transitive via tsx, vitest, and esbuild-register \u2014 and is never in a shipped bundle or runtime code path. Lisa-managed projects install via bun/npm (not the Deno module path) and do not use attacker-controlled NPM_CONFIG_REGISTRY at install. Remove once the tsx/vitest/esbuild-register chain bumps esbuild >= 0.28.1."
     }
   ]
 }

package/typescript/copy-overwrite/eslint.config.ts

@@ -7,11 +7,16 @@
  * ESLint 9 Flat Config
  *
  * Thin wrapper around @codyswann/lisa eslint config factory.
- * Customize via eslint.config.local.ts and eslint.thresholds.json.
+ * Customize via eslint.config.local.ts, eslint.thresholds.json, and the
+ * optional (create-only) eslint.ignore.config.local.json — its `ignores` are
+ * merged into the ignore list so host customizations survive the
+ * copy-overwrite of eslint.ignore.config.json on each Lisa update.
  *
  * @see https://eslint.org/docs/latest/use/configure/configuration-files-new
  * @module eslint.config
  */
+import { existsSync } from "fs";
+import { createRequire } from "module";
 import path from "path";
 import { fileURLToPath } from "url";
 
@@ -25,14 +30,33 @@ import ignoreConfig from "./eslint.ignore.config.json" with { type: "json" };
 import thresholdsConfig from "./eslint.thresholds.json" with { type: "json" };
 import localConfig from "./eslint.config.local";
 
+const require = createRequire(import.meta.url);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-export default [
+// Merge the optional project-owned eslint.ignore.config.local.json (create-only,
+// never copy-overwritten) so host ignore customizations are not wiped when Lisa
+// overwrites eslint.ignore.config.json on update.
+const localIgnores: string[] = existsSync(
+  path.join(__dirname, "eslint.ignore.config.local.json")
+)
+  ? (require("./eslint.ignore.config.local.json").ignores ?? [])
+  : [];
+
+// Annotate with the factory's return type so `tsc --noEmit` under
+// `declaration: true` does not surface @eslint/core's `RulesConfig` in the
+// emitted declaration (TS2883). Do NOT import `Linter` from "eslint" directly —
+// that trips knip's unlisted-dependency check.
+const config: ReturnType<typeof getTypescriptConfig> = [
   ...getTypescriptConfig({
     tsconfigRootDir: __dirname,
-    ignorePatterns: ignoreConfig.ignores || defaultIgnores,
+    ignorePatterns: [
+      ...(ignoreConfig.ignores || defaultIgnores),
+      ...localIgnores,
+    ],
     thresholds: { ...defaultThresholds, ...thresholdsConfig },
   }),
   ...localConfig,
 ];
+
+export default config;

package/typescript/copy-overwrite/eslint.slow.config.ts

@@ -9,10 +9,41 @@
  * Thin wrapper around @codyswann/lisa slow eslint config factory.
  * Run periodically via `lint:slow` rather than on every lint pass.
  *
+ * The optional (create-only) eslint.ignore.config.local.json `ignores` are
+ * merged into the ignore list so host customizations survive the
+ * copy-overwrite of eslint.ignore.config.json on each Lisa update.
+ *
  * @see https://github.com/import-js/eslint-plugin-import
  * @module eslint.slow.config
  */
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import path from "path";
+import { fileURLToPath } from "url";
+
 import { getSlowConfig } from "@codyswann/lisa/eslint/slow";
+
 import ignoreConfig from "./eslint.ignore.config.json" with { type: "json" };
 
-export default getSlowConfig({ ignorePatterns: ignoreConfig.ignores || [] });
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Merge the optional project-owned eslint.ignore.config.local.json (create-only,
+// never copy-overwritten) so host ignore customizations are not wiped when Lisa
+// overwrites eslint.ignore.config.json on update.
+const localIgnores: string[] = existsSync(
+  path.join(__dirname, "eslint.ignore.config.local.json")
+)
+  ? (require("./eslint.ignore.config.local.json").ignores ?? [])
+  : [];
+
+// Annotate with the factory's return type so `tsc --noEmit` under
+// `declaration: true` does not surface @eslint/core's `RulesConfig` in the
+// emitted declaration (TS2883). Do NOT import `Linter` from "eslint" directly —
+// that trips knip's unlisted-dependency check.
+const config: ReturnType<typeof getSlowConfig> = getSlowConfig({
+  ignorePatterns: [...(ignoreConfig.ignores || []), ...localIgnores],
+});
+
+export default config;

package/typescript/package-lisa/package.lisa.json

@@ -35,7 +35,8 @@
       "undici": ">=6.27.0",
       "vite": ">=8.0.16",
       "ws": ">=8.21.0",
-      "form-data": ">=4.0.6"
+      "form-data": ">=4.0.6",
+      "systeminformation": ">=5.27.14"
     },
     "overrides": {
       "@isaacs/brace-expansion": "^5.0.1",
@@ -47,7 +48,8 @@
       "undici": ">=6.27.0",
       "vite": "^8.0.16",
       "ws": ">=8.21.0",
-      "form-data": ">=4.0.6"
+      "form-data": ">=4.0.6",
+      "systeminformation": ">=5.27.14"
     }
   },
   "defaults": {