@tryinget/pi-agent-vent 0.1.0

package/scripts/validate-structure.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+
+let failed = false;
+const errors = [];
+
+function fail(msg) {
+  errors.push(msg);
+  failed = true;
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function readTextSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+function readCopierAnswer(key) {
+  const answers = readTextSafe(".copier-answers.yml");
+  if (!answers) return undefined;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`^${escaped}:\\s*['"]?([^'"\\r\\n]+)['"]?\\s*$`, "m").exec(answers);
+  return match?.[1]?.trim();
+}
+
+function expectedReleaseConfigMode() {
+  return readCopierAnswer("release_config_mode") ?? "component";
+}
+
+function validateScopedPackageName(p) {
+  const npmOrg = readCopierAnswer("npm_org");
+  const repoName = readCopierAnswer("repo_name");
+  if (!npmOrg || !repoName) {
+    fail(".copier-answers.yml must include npm_org and repo_name for package name validation");
+    return;
+  }
+
+  const expectedName = `@${npmOrg.replace(/^@/, "")}/${repoName}`;
+  if (p.name !== expectedName) {
+    fail(`package.json name must be scoped npm identity '${expectedName}' (got '${p.name}')`);
+  }
+}
+
+function validatePackageJson() {
+  const p = readJsonSafe("package.json");
+  if (!p) {
+    fail("Failed to parse package.json");
+    return;
+  }
+
+  validateScopedPackageName(p);
+
+  if (!Array.isArray(p.keywords) || !p.keywords.includes("pi-package")) {
+    fail("package.json missing keywords entry: pi-package");
+  }
+  if (!Array.isArray(p.keywords) || !p.keywords.includes("pi-extension")) {
+    fail("package.json missing keywords entry: pi-extension");
+  }
+
+  const ext = p.pi?.extensions;
+  if (!Array.isArray(ext) || ext.length < 1) {
+    fail("package.json missing pi.extensions array");
+  } else {
+    for (const entry of ext) {
+      const normalized = entry.replace(/^\.\//, "");
+      if (!fs.existsSync(normalized)) {
+        fail(`pi.extensions entry does not exist: ${entry}`);
+      }
+    }
+  }
+
+  const prompts = p.pi?.prompts;
+  if (!Array.isArray(prompts) || prompts.length < 1) {
+    fail("package.json missing pi.prompts array");
+  } else {
+    for (const entry of prompts) {
+      const normalized = entry.replace(/\/$/, "").replace(/^\.\//, "");
+      if (!fs.existsSync(normalized)) {
+        fail(`pi.prompts entry does not exist: ${entry}`);
+      }
+    }
+  }
+
+  const requiredPeers = ["@mariozechner/pi-coding-agent", "@mariozechner/pi-ai"];
+  for (const peer of requiredPeers) {
+    if (typeof p.peerDependencies?.[peer] !== "string") {
+      fail(`package.json peerDependencies must include ${peer}`);
+    }
+  }
+
+  const scriptExpectations = {
+    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",
+  };
+
+  for (const [scriptName, expected] of Object.entries(scriptExpectations)) {
+    if (p.scripts?.[scriptName] !== expected) {
+      fail(`package.json scripts.${scriptName} must be '${expected}'`);
+    }
+  }
+
+  if (p.publishConfig?.registry !== "https://registry.npmjs.org/") {
+    fail("package.json publishConfig.registry must be 'https://registry.npmjs.org/'");
+  }
+
+  if (p.publishConfig?.access !== "public") {
+    fail("package.json publishConfig.access must be 'public'");
+  }
+
+  if (p.engines?.node !== ">=22") {
+    fail("package.json engines.node must be '>=22'");
+  }
+
+  const expectedWorkspacePath = readCopierAnswer("workspace_relative_path");
+  if (typeof p.repository?.directory !== "string" || p.repository.directory.length === 0) {
+    fail("package.json repository.directory must be set for monorepo package mode");
+  } else if (expectedWorkspacePath && p.repository.directory !== expectedWorkspacePath) {
+    fail(
+      `package.json repository.directory must match .copier-answers.yml workspace_relative_path '${expectedWorkspacePath}' (got '${p.repository.directory}')`,
+    );
+  }
+
+  const templateMeta = p["x-pi-template"];
+  if (!templateMeta || typeof templateMeta !== "object") {
+    fail("package.json must include x-pi-template metadata");
+  } else {
+    if (!["simple-package", "monorepo-package"].includes(templateMeta.scaffoldMode)) {
+      fail(
+        "package.json x-pi-template.scaffoldMode must be 'simple-package' or legacy alias 'monorepo-package'",
+      );
+    }
+    const expectedReleaseComponent = readCopierAnswer("release_component_key");
+    if (typeof templateMeta.workspacePath !== "string" || templateMeta.workspacePath.length === 0) {
+      fail("package.json x-pi-template.workspacePath must be non-empty");
+    } else if (expectedWorkspacePath && templateMeta.workspacePath !== expectedWorkspacePath) {
+      fail(
+        `package.json x-pi-template.workspacePath must match .copier-answers.yml workspace_relative_path '${expectedWorkspacePath}' (got '${templateMeta.workspacePath}')`,
+      );
+    }
+    if (
+      typeof templateMeta.releaseComponent !== "string" ||
+      templateMeta.releaseComponent.length === 0
+    ) {
+      fail("package.json x-pi-template.releaseComponent must be non-empty");
+    } else if (
+      expectedReleaseComponent &&
+      templateMeta.releaseComponent !== expectedReleaseComponent
+    ) {
+      fail(
+        `package.json x-pi-template.releaseComponent must match .copier-answers.yml release_component_key '${expectedReleaseComponent}' (got '${templateMeta.releaseComponent}')`,
+      );
+    }
+    if (!["component", "none"].includes(templateMeta.releaseConfigMode)) {
+      fail("package.json x-pi-template.releaseConfigMode must be 'component' or 'none'");
+    }
+    const expectedMode = expectedReleaseConfigMode();
+    if (templateMeta.releaseConfigMode !== expectedMode) {
+      fail(
+        `package.json x-pi-template.releaseConfigMode must match .copier-answers.yml release_config_mode '${expectedMode}' (got '${templateMeta.releaseConfigMode}')`,
+      );
+    }
+  }
+
+  const biomeVersion = p.devDependencies?.["@biomejs/biome"];
+  if (typeof biomeVersion !== "string") {
+    fail("package.json devDependencies must include @biomejs/biome");
+  }
+
+  if (!Array.isArray(p.files) || p.files.length < 1) {
+    fail("package.json must define a non-empty files array");
+  } else {
+    if (!p.files.includes("prompts")) {
+      fail("package.json files must include 'prompts'");
+    }
+    if (!p.files.includes("examples")) {
+      fail("package.json files must include 'examples'");
+    }
+    if (!p.files.includes("policy/security-policy.json")) {
+      fail("package.json files must include 'policy/security-policy.json'");
+    }
+    if (!p.files.includes("policy/engineering-lane.json")) {
+      fail("package.json files must include 'policy/engineering-lane.json'");
+    }
+
+    for (const entry of ext) {
+      const normalized = entry.replace(/^\.\//, "");
+      if (!p.files.includes(normalized)) {
+        fail(`package.json files must include extension artifact: ${normalized}`);
+      }
+    }
+  }
+}
+
+function validateEngineeringLane() {
+  const stackLane = readJsonSafe("policy/engineering-lane.json");
+  if (!stackLane) {
+    fail("Failed to parse policy/engineering-lane.json");
+    return;
+  }
+
+  if (stackLane.lane !== "ts") {
+    fail("policy/engineering-lane.json lane must be 'ts'");
+  }
+
+  const laneName = stackLane.engineering_core?.lane;
+  if (laneName !== "pi-ts") {
+    fail("policy/engineering-lane.json engineering_core.lane must be 'pi-ts'");
+  }
+}
+
+function main() {
+  validatePackageJson();
+  validateEngineeringLane();
+
+  if (failed) {
+    for (const error of errors) {
+      console.error(error);
+    }
+    console.error(`Validation failed with ${errors.length} issue(s).`);
+    process.exit(1);
+  }
+
+  console.log("Node.js validation passed.");
+}
+
+main();

package/scripts/validate-structure.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+required_files=(
+  "README.md"
+  "LICENSE"
+  "AGENTS.md"
+  "CHANGELOG.md"
+  "biome.jsonc"
+  ".vscode/settings.json"
+  ".copier-answers.yml"
+  "package.json"
+  "next_session_prompt.md"
+  "docs/org/operating_model.md"
+  "docs/project/foundation.md"
+  "docs/project/vision.md"
+  "docs/project/incentives.md"
+  "docs/project/resources.md"
+  "docs/project/contributing.md"
+  "docs/project/extension-sop.md"
+  "docs/project/trusted-publishing.md"
+  "docs/engineering.local.md"
+  "docs/adr/.gitkeep"
+  "policy/engineering-lane.json"
+  "policy/security-policy.json"
+  ".pi/prompts/commit.md"
+  "scripts/docs-list.sh"
+  "scripts/release-artifact-check.mjs"
+  "scripts/release-check.sh"
+  "scripts/validate-structure.sh"
+  "scripts/validate-structure.mjs"
+  "scripts/quality-gate.sh"
+  "prompts/implementation-planning.md"
+  "prompts/security-review.md"
+)
+
+required_dirs=(
+  ".vscode"
+  "docs"
+  "docs/adr"
+  "docs/org"
+  "docs/project"
+  "extensions"
+  "examples"
+  "external"
+  "ontology"
+  "policy"
+  "scripts"
+  "src"
+  "tests"
+  ".pi"
+  ".pi/prompts"
+  "prompts"
+)
+
+required_executables=(
+  "scripts/docs-list.sh"
+  "scripts/release-check.sh"
+  "scripts/validate-structure.sh"
+  "scripts/validate-structure.mjs"
+  "scripts/quality-gate.sh"
+)
+
+errors=0
+
+for required_file in "${required_files[@]}"; do
+  if [[ ! -f "$required_file" ]]; then
+    echo "Missing required file: $required_file" >&2
+    ((errors+=1))
+  fi
+done
+
+for required_dir in "${required_dirs[@]}"; do
+  if [[ ! -d "$required_dir" ]]; then
+    echo "Missing required directory: $required_dir" >&2
+    ((errors+=1))
+  fi
+done
+
+for executable in "${required_executables[@]}"; do
+  if [[ ! -x "$executable" ]]; then
+    echo "Expected executable bit on: $executable" >&2
+    ((errors+=1))
+  fi
+done
+
+for copier_key in "_src_path:" "repo_name:" "command_name:" "scaffold_mode:" "workspace_relative_path:" "release_component_key:" "release_config_mode:"; do
+  if ! grep -q "^${copier_key}" ".copier-answers.yml"; then
+    echo "Missing copier answer key in .copier-answers.yml: ${copier_key}" >&2
+    ((errors+=1))
+  fi
+done
+
+if [[ -d ".github" ]]; then
+  echo "Monorepo package scaffold must not create package-local .github directory" >&2
+  ((errors+=1))
+fi
+
+if [[ -d ".githooks" ]]; then
+  echo "Monorepo package scaffold must not create package-local .githooks directory" >&2
+  ((errors+=1))
+fi
+
+if ! grep -q '^\*\.tgz$' ".gitignore"; then
+  echo ".gitignore must ignore npm tarball outputs (*.tgz)" >&2
+  ((errors+=1))
+fi
+
+if command -v node >/dev/null 2>&1; then
+  if ! node "$ROOT_DIR/scripts/validate-structure.mjs"; then
+    ((errors+=1))
+  fi
+fi
+
+while IFS= read -r -d '' markdown_file; do
+  if [[ "$(head -n 1 "$markdown_file")" != "---" ]]; then
+    echo "Missing YAML frontmatter start in: $markdown_file" >&2
+    ((errors+=1))
+    continue
+  fi
+
+  if ! grep -q "^system4d:" "$markdown_file"; then
+    echo "Missing system4d section in: $markdown_file" >&2
+    ((errors+=1))
+    continue
+  fi
+
+  for key in container compass engine fog; do
+    if ! grep -q "^  $key:" "$markdown_file"; then
+      echo "Missing system4d.$key in: $markdown_file" >&2
+      ((errors+=1))
+    fi
+  done
+
+done < <(find . -type f -name "*.md" ! -path "./node_modules/*" ! -path "./.git/*" -print0)
+
+if [[ "$errors" -gt 0 ]]; then
+  echo "Structure validation failed with $errors issue(s)." >&2
+  exit 1
+fi
+
+echo "Structure validation passed."