@tryinget/pi-agent-vent 0.1.0

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@tryinget/pi-agent-vent",
+  "version": "0.1.0",
+  "description": "Local pi tool for agents to record recurring frustrations, bugs, and workflow friction without creating incidents or external telemetry",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tryingET/pi-extensions.git",
+    "directory": "packages/pi-agent-vent"
+  },
+  "bugs": {
+    "url": "https://github.com/tryingET/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/tryingET/pi-extensions/tree/main/packages/pi-agent-vent",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "agent-vent",
+    "monorepo",
+    "agent-feedback",
+    "frustration-capture",
+    "local-diagnostics",
+    "incident-candidate"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "fix": "bash ./scripts/quality-gate.sh fix",
+    "lint": "bash ./scripts/quality-gate.sh lint",
+    "typecheck": "bash ./scripts/quality-gate.sh typecheck",
+    "quality:pre-commit": "bash ./scripts/quality-gate.sh pre-commit",
+    "quality:pre-push": "bash ./scripts/quality-gate.sh pre-push",
+    "quality:ci": "bash ./scripts/quality-gate.sh ci",
+    "check": "npm run quality:ci",
+    "test": "npm run quality:ci",
+    "docs:list": "bash ./scripts/docs-list.sh",
+    "docs:list:workspace": "bash ./scripts/docs-list.sh --workspace --discover",
+    "docs:list:json": "bash ./scripts/docs-list.sh --json",
+    "release:check": "bash ./scripts/release-check.sh",
+    "release:check:quick": "SKIP_PI_SMOKE=1 bash ./scripts/release-check.sh"
+  },
+  "files": [
+    "extensions/agent-vent.ts",
+    "src/vent-store.js",
+    "scripts",
+    "tests",
+    "biome.jsonc",
+    "prompts",
+    "examples",
+    "policy/security-policy.json",
+    "policy/engineering-lane.json",
+    "docs/engineering.local.md",
+    "docs/project/vision.md",
+    "docs/project/product-posture.md",
+    "docs/project/2026-05-21-agent-vent-design.md",
+    "docs/project/2026-05-21-agent-vent-implementation-plan.md",
+    "docs/project/extension-sop.md",
+    "docs/project/trusted-publishing.md",
+    "docs/adr/2026-05-22-agent-vent-retention-delete-policy.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/agent-vent.ts"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "x-pi-template": {
+    "scaffoldMode": "simple-package",
+    "workspacePath": "packages/pi-agent-vent",
+    "releaseComponent": "pi-agent-vent",
+    "releaseConfigMode": "component"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.14"
+  },
+  "overrides": {
+    "fast-xml-parser": "5.3.6"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "typebox": "^1.0.0"
+  }
+}

package/policy/engineering-lane.json

@@ -0,0 +1,22 @@
+{
+  "lane": "ts",
+  "engineering_core": {
+    "tool": "engineering-core",
+    "lane": "pi-ts",
+    "repository": "https://github.com/tryingET/core_engineering-core",
+    "ref": "workspace-local-unpinned",
+    "command": "uv tool -n run --from ~/ai-society/core/engineering-core engineering-core show pi-ts",
+    "catalog_command": "uv tool -n run --from ~/ai-society/core/engineering-core engineering-core catalog --pretty",
+    "list_disciplines_command": "uv tool -n run --from ~/ai-society/core/engineering-core engineering-core list-disciplines",
+    "list_templates_command": "uv tool -n run --from ~/ai-society/core/engineering-core engineering-core list-templates",
+    "disciplines": [
+      "validation",
+      "testing",
+      "security-privacy",
+      "documentation",
+      "dependency-governance",
+      "specification-and-dsls",
+      "engineering-reasoning"
+    ]
+  }
+}

package/policy/security-policy.json

@@ -0,0 +1,10 @@
+{
+  "default": {
+    "maxRiskScore": 70,
+    "requireIntegrity": true,
+    "requireSignatures": false,
+    "allowNpmDiffFallback": false,
+    "minReleaseAgeHours": 0
+  },
+  "packages": {}
+}

package/prompts/implementation-planning.md

@@ -0,0 +1,20 @@
+---
+summary: "Monorepo package implementation planning prompt template."
+read_when:
+  - "Using or updating the monorepo package implementation-planning prompt template."
+description: Draft an implementation plan for a requested change
+system4d:
+  container: "Prompt template for implementation planning."
+  compass: "Turn requests into actionable, risk-aware plans."
+  engine: "Scope -> tasks -> validation -> rollout."
+  fog: "Hidden constraints unless assumptions are surfaced."
+---
+
+Create an implementation plan for this request: $@
+
+Include:
+- Scope and non-goals
+- Key risks and mitigations
+- Step-by-step implementation tasks
+- Validation commands and expected outcomes
+- Rollout and rollback notes

package/prompts/security-review.md

@@ -0,0 +1,20 @@
+---
+summary: "Monorepo package security review prompt template."
+read_when:
+  - "Using or updating the monorepo package security-review prompt template."
+description: Review a change for security risks and mitigations
+system4d:
+  container: "Prompt template for security-focused review."
+  compass: "Identify practical vulnerabilities before release."
+  engine: "Threats -> impact -> mitigations -> verification."
+  fog: "Partial context can hide exploit paths."
+---
+
+Review this change for security concerns: $@
+
+Focus on:
+- Input validation and injection risk
+- Privilege boundaries and secret handling
+- Dependency and supply-chain risk
+- Safe failure modes and logging
+- Concrete remediations with priority

package/scripts/docs-list.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DEFAULT_SCRIPT="$HOME/ai-society/core/agent-scripts/scripts/docs-list.mjs"
+LOCAL_FALLBACK_SCRIPT="$ROOT_DIR/scripts/docs-list.mjs"
+
+usage() {
+  cat <<'USAGE'
+Usage: ./scripts/docs-list.sh [docs-list args]
+
+Resolves docs-list script in this order:
+1) DOCS_LIST_SCRIPT env var (absolute/relative path)
+2) Local fallback: ./scripts/docs-list.mjs
+3) Default global path: ~/ai-society/core/agent-scripts/scripts/docs-list.mjs
+
+Examples:
+  ./scripts/docs-list.sh
+  ./scripts/docs-list.sh --workspace --discover
+  ./scripts/docs-list.sh --json
+USAGE
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "Error: node is required to run docs-list." >&2
+  exit 1
+fi
+
+SCRIPT_PATH=""
+
+if [[ -n "${DOCS_LIST_SCRIPT:-}" ]]; then
+  SCRIPT_PATH="${DOCS_LIST_SCRIPT}"
+elif [[ -f "$LOCAL_FALLBACK_SCRIPT" ]]; then
+  SCRIPT_PATH="$LOCAL_FALLBACK_SCRIPT"
+else
+  SCRIPT_PATH="$DEFAULT_SCRIPT"
+fi
+
+if [[ ! -f "$SCRIPT_PATH" ]]; then
+  echo "Error: docs-list script not found: $SCRIPT_PATH" >&2
+  echo "Set DOCS_LIST_SCRIPT to your docs-list.mjs path, or place docs-list script at: $DEFAULT_SCRIPT" >&2
+  exit 1
+fi
+
+node "$SCRIPT_PATH" "$@"

package/scripts/quality-gate.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SEARCH_DIR="$ROOT_DIR"
+OVERRIDE_GATE="${PACKAGE_QUALITY_GATE_SCRIPT:-}"
+
+if [[ -n "$OVERRIDE_GATE" ]]; then
+  if [[ -f "$OVERRIDE_GATE" ]]; then
+    exec bash "$OVERRIDE_GATE" "${1:-}" "$ROOT_DIR"
+  fi
+  echo "error: PACKAGE_QUALITY_GATE_SCRIPT does not exist: $OVERRIDE_GATE" >&2
+  exit 1
+fi
+
+while [[ "$SEARCH_DIR" != "/" ]]; do
+  if [[ -x "$SEARCH_DIR/scripts/package-quality-gate.sh" ]]; then
+    exec bash "$SEARCH_DIR/scripts/package-quality-gate.sh" "${1:-}" "$ROOT_DIR"
+  fi
+  SEARCH_DIR="$(dirname "$SEARCH_DIR")"
+done
+
+stage="${1:-}"
+case "$stage" in
+  lint|fix|typecheck|test|pre-commit|pre-push|ci) ;;
+  *)
+    echo "Usage: bash ./scripts/quality-gate.sh <lint|fix|typecheck|test|pre-commit|pre-push|ci>" >&2
+    exit 1
+    ;;
+esac
+
+relative_root() {
+  basename "$ROOT_DIR"
+}
+
+has_biome_config() {
+  [[ -f "$ROOT_DIR/biome.json" ]] || [[ -f "$ROOT_DIR/biome.jsonc" ]]
+}
+
+run_biome() {
+  if ! has_biome_config; then
+    echo "lint: skipped ($(relative_root), no biome config found)"
+    return 0
+  fi
+  if [[ ! -x "$ROOT_DIR/node_modules/.bin/biome" ]]; then
+    echo "biome: skipped ($(relative_root), local biome binary unavailable; run npm install to enable lint)."
+    return 0
+  fi
+
+  # Runtime tarballs do not necessarily include a VCS ignore file. The package biome config
+  # already excludes node_modules/dist/coverage, so disable VCS-ignore-file loading there.
+  local -a vcs_args=()
+  if [[ ! -f "$ROOT_DIR/.gitignore" ]]; then
+    vcs_args+=(--vcs-use-ignore-file=false)
+  fi
+
+  (cd "$ROOT_DIR" && ./node_modules/.bin/biome "$@" "${vcs_args[@]}")
+}
+
+run_lint() {
+  run_biome check --no-errors-on-unmatched .
+}
+
+run_fix() {
+  run_biome check --write --no-errors-on-unmatched .
+}
+
+run_typecheck() {
+  if [[ ! -f "$ROOT_DIR/tsconfig.json" ]]; then
+    echo "typecheck: skipped ($(relative_root), no tsconfig.json found)"
+    return 0
+  fi
+  if [[ -x "$ROOT_DIR/node_modules/.bin/tsgo" ]]; then
+    (cd "$ROOT_DIR" && ./node_modules/.bin/tsgo --noEmit)
+    return 0
+  fi
+  if [[ -x "$ROOT_DIR/node_modules/.bin/tsc" ]]; then
+    (cd "$ROOT_DIR" && ./node_modules/.bin/tsc --noEmit)
+    return 0
+  fi
+  echo "typecheck: skipped ($(relative_root), tsconfig found but no local tsgo/tsc binary)."
+}
+
+run_tests() {
+  if [[ ! -d "$ROOT_DIR/tests" ]]; then
+    echo "tests: skipped ($(relative_root), no tests directory found)"
+    return 0
+  fi
+  mapfile -t test_files < <(
+    cd "$ROOT_DIR"
+    find tests -type f \( \
+      -name '*.test.js' -o \
+      -name '*.test.mjs' -o \
+      -name '*.test.cjs' -o \
+      -name '*.test.ts' -o \
+      -name '*.test.tsx' -o \
+      -name '*.test.mts' -o \
+      -name '*.test.cts' \
+    \) | LC_ALL=C sort
+  )
+  if [[ "${#test_files[@]}" -eq 0 ]]; then
+    echo "tests: skipped ($(relative_root), no test files found)"
+    return 0
+  fi
+  local needs_tsx="false"
+  local test_file
+  for test_file in "${test_files[@]}"; do
+    case "$test_file" in
+      *.test.ts|*.test.tsx|*.test.mts|*.test.cts)
+        needs_tsx="true"
+        break
+        ;;
+    esac
+  done
+
+  if [[ "$needs_tsx" == "true" ]]; then
+    if [[ ! -x "$ROOT_DIR/node_modules/.bin/tsx" ]]; then
+      echo "tests: TypeScript test files detected but local tsx binary is unavailable." >&2
+      exit 1
+    fi
+    (cd "$ROOT_DIR" && node --import tsx --test "${test_files[@]}")
+    return 0
+  fi
+
+  (cd "$ROOT_DIR" && node --test "${test_files[@]}")
+}
+
+run_structure_if_source_checkout() {
+  if [[ -f "$ROOT_DIR/.copier-answers.yml" && -f "$ROOT_DIR/scripts/validate-structure.sh" ]]; then
+    (cd "$ROOT_DIR" && bash ./scripts/validate-structure.sh)
+  else
+    echo "structure: skipped ($(relative_root), source-checkout structure contract not present)"
+  fi
+}
+
+echo "==> package local quality gate: $(relative_root) [$stage]"
+echo "note: monorepo root gate not found; running self-contained package fallback."
+
+case "$stage" in
+  lint)
+    run_lint
+    ;;
+  fix)
+    run_fix
+    ;;
+  typecheck)
+    run_typecheck
+    ;;
+  test)
+    run_tests
+    ;;
+  pre-commit)
+    run_structure_if_source_checkout
+    run_lint
+    ;;
+  pre-push)
+    run_structure_if_source_checkout
+    run_lint
+    run_typecheck
+    run_tests
+    ;;
+  ci)
+    run_structure_if_source_checkout
+    run_lint
+    run_typecheck
+    run_tests
+    ;;
+esac

package/scripts/release-artifact-check.mjs

@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const normalizePackPath = (value) => String(value).replace(/^\.\//, "").replace(/\\/g, "/");
+
+export const assertSafePackPath = (filePath) => {
+  if (path.posix.isAbsolute(filePath) || filePath === ".." || filePath.split("/").includes("..")) {
+    throw new Error(`npm pack output contains unsafe package path: ${filePath}`);
+  }
+  return filePath;
+};
+
+export const parsePackJson = (packJsonText) => {
+  let pack;
+  try {
+    pack = JSON.parse(packJsonText || "[]");
+  } catch (error) {
+    throw new Error(`Could not parse npm pack --dry-run --json output: ${error.message}`);
+  }
+
+  if (!Array.isArray(pack) || !pack[0] || !Array.isArray(pack[0].files)) {
+    throw new Error("Could not parse npm pack --dry-run --json output.");
+  }
+
+  return pack[0].files
+    .map((file) => normalizePackPath(String(file.path || "")))
+    .filter(Boolean)
+    .map(assertSafePackPath)
+    .sort();
+};
+
+export const readPackageFilesContract = (packageJsonPath = "package.json") => {
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  const filesEntries = Array.isArray(pkg.files)
+    ? pkg.files.map((entry) => normalizePackPath(String(entry).trim())).filter(Boolean)
+    : [];
+
+  if (filesEntries.length === 0) {
+    throw new Error(
+      "package.json must define a non-empty files array for deterministic publish artifacts.",
+    );
+  }
+
+  return filesEntries;
+};
+
+const isAlwaysIncluded = (filePath) =>
+  /^README(?:\.[^/]+)?$/i.test(filePath) ||
+  /^LICENSE(?:\.[^/]+)?$/i.test(filePath) ||
+  /^NOTICE(?:\.[^/]+)?$/i.test(filePath);
+
+export const validatePackageFilesWhitelist = ({
+  actualFiles,
+  filesEntries,
+  cwd = process.cwd(),
+}) => {
+  const actualSet = new Set(actualFiles);
+  const expectedExact = new Set(["package.json"]);
+  const expectedDirPrefixes = [];
+
+  for (const entry of filesEntries) {
+    if (/[*?[]/.test(entry)) {
+      throw new Error(
+        `Unsupported files[] wildcard entry; use exact files or directories: ${entry}`,
+      );
+    }
+
+    const fullPath = path.resolve(cwd, entry);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`files[] entry does not exist: ${entry}`);
+    }
+
+    const stat = fs.statSync(fullPath);
+    if (stat.isDirectory()) {
+      expectedDirPrefixes.push(entry.endsWith("/") ? entry : `${entry}/`);
+    } else {
+      expectedExact.add(entry);
+    }
+  }
+
+  const missing = [];
+  for (const filePath of expectedExact) {
+    if (!actualSet.has(filePath)) {
+      missing.push(filePath);
+    }
+  }
+  for (const prefix of expectedDirPrefixes) {
+    if (!actualFiles.some((filePath) => filePath.startsWith(prefix))) {
+      missing.push(`${prefix}*`);
+    }
+  }
+
+  const extra = actualFiles.filter((filePath) => {
+    if (expectedExact.has(filePath)) return false;
+    if (expectedDirPrefixes.some((prefix) => filePath.startsWith(prefix))) return false;
+    if (isAlwaysIncluded(filePath)) return false;
+    return true;
+  });
+
+  return { missing, extra };
+};
+
+export const isExternalMarkdownDestination = (target) =>
+  /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(target) || target.startsWith("//");
+
+export const markdownDestination = (rawTarget) => {
+  let target = String(rawTarget || "").trim();
+  if (!target) return "";
+  if (target.startsWith("<")) {
+    const closingAngle = target.indexOf(">");
+    target = closingAngle >= 0 ? target.slice(1, closingAngle).trim() : target;
+  } else {
+    target = target.split(/\s+/, 1)[0] || "";
+  }
+  try {
+    return decodeURI(target);
+  } catch {
+    return target;
+  }
+};
+
+const markdownLinkPattern = /!?\[[^\]\n]*\]\(([^)\n]+)\)/g;
+const referenceLinkDefinitionPattern = /^[ \t]{0,3}\[[^\]\n]+\]:[ \t]*(\S.*)$/gm;
+
+const collectMarkdownDestinations = (markdown) => [
+  ...[...markdown.matchAll(markdownLinkPattern)].map((match) => match[1]),
+  ...[...markdown.matchAll(referenceLinkDefinitionPattern)].map((match) => match[1]),
+];
+
+export const collectPackagedMarkdownLinkFailures = ({ actualFiles, readFile }) => {
+  const actualSet = new Set(actualFiles);
+  const failures = [];
+  const packagedMarkdownFiles = actualFiles.filter((filePath) =>
+    filePath.toLowerCase().endsWith(".md"),
+  );
+
+  for (const markdownPath of packagedMarkdownFiles) {
+    const markdown = readFile(markdownPath);
+    for (const rawTarget of collectMarkdownDestinations(markdown)) {
+      const target = markdownDestination(rawTarget);
+      if (!target || target.startsWith("#") || isExternalMarkdownDestination(target)) {
+        continue;
+      }
+
+      const targetWithoutFragment = target.split("#", 1)[0].split("?", 1)[0];
+      if (!targetWithoutFragment) {
+        continue;
+      }
+
+      const normalizedTarget = normalizePackPath(
+        path.posix.normalize(
+          path.posix.join(path.posix.dirname(markdownPath), targetWithoutFragment),
+        ),
+      );
+      if (
+        path.posix.isAbsolute(targetWithoutFragment) ||
+        normalizedTarget === ".." ||
+        normalizedTarget.startsWith("../")
+      ) {
+        failures.push(`${markdownPath}: local link escapes package root: ${target}`);
+        continue;
+      }
+
+      const directoryPrefix = normalizedTarget.endsWith("/")
+        ? normalizedTarget
+        : `${normalizedTarget}/`;
+      const targetIsPackaged =
+        actualSet.has(normalizedTarget) ||
+        actualSet.has(`${normalizedTarget}.md`) ||
+        actualFiles.some((filePath) => filePath.startsWith(directoryPrefix));
+      if (!targetIsPackaged) {
+        failures.push(`${markdownPath}: local link missing from npm artifact: ${target}`);
+      }
+    }
+  }
+
+  return { failures, packagedMarkdownCount: packagedMarkdownFiles.length };
+};
+
+export const runReleaseArtifactCheck = ({
+  packJsonText,
+  cwd = process.cwd(),
+  log = console.log,
+}) => {
+  const actualFiles = parsePackJson(packJsonText);
+  const filesEntries = readPackageFilesContract(path.join(cwd, "package.json"));
+  const whitelist = validatePackageFilesWhitelist({ actualFiles, filesEntries, cwd });
+
+  if (whitelist.missing.length || whitelist.extra.length) {
+    const lines = ["Publish file whitelist mismatch."];
+    if (whitelist.missing.length) lines.push(`Missing: ${whitelist.missing.join(", ")}`);
+    if (whitelist.extra.length) lines.push(`Extra: ${whitelist.extra.join(", ")}`);
+    throw new Error(lines.join("\n"));
+  }
+
+  const markdown = collectPackagedMarkdownLinkFailures({
+    actualFiles,
+    readFile: (filePath) => fs.readFileSync(path.join(cwd, filePath), "utf8"),
+  });
+
+  if (markdown.failures.length) {
+    throw new Error(
+      [
+        "Packaged Markdown link check failed.",
+        ...markdown.failures.map((failure) => `- ${failure}`),
+      ].join("\n"),
+    );
+  }
+
+  log(`File whitelist OK (${actualFiles.length} files).`);
+  log(`Packaged Markdown links OK (${markdown.packagedMarkdownCount} files).`);
+};
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    runReleaseArtifactCheck({ packJsonText: process.env.PACK_JSON || "[]" });
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}