@piagent/platform 1.0.0

package/scripts/import-agent-instructions.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// Imports instruction files written for other agents into AGENTS.md.
+//
+// AGENTS.md is the format this platform reads, and the one the wider ecosystem
+// converged on, so the flow is deliberately one-way: legacy formats are folded
+// in and then stop being a second source of truth.
+//
+// Imported text is DATA, not instruction. It is quoted into a clearly labelled
+// section and never interpreted here: a repository's instruction file is
+// attacker-controlled in the general case, and anything that could change
+// protected paths, permission profile, or verify commands is reported for a
+// human to act on rather than applied.
+import fs from "node:fs";
+import path from "node:path";
+
+// Ordered: earlier sources win a conflict. AGENTS.md itself always outranks
+// every import, which is what makes repeated runs safe.
+const SOURCES = [
+  { id: "claude-md", label: "CLAUDE.md", kind: "file", rel: "CLAUDE.md" },
+  { id: "claude-rules", label: ".claude/rules", kind: "dir", rel: ".claude/rules", ext: [".md"] },
+  { id: "cursor-rules", label: ".cursor/rules", kind: "dir", rel: ".cursor/rules", ext: [".md", ".mdc"] },
+  { id: "copilot", label: ".github/copilot-instructions.md", kind: "file", rel: ".github/copilot-instructions.md" }
+];
+
+const IMPORT_HEADING = "## Imported agent instructions";
+
+// Directives that would change what the guard enforces. Matching text is still
+// imported verbatim, but it is surfaced so a human decides rather than having
+// the profile quietly rewritten by a file from an untrusted repository.
+const SENSITIVE_PATTERNS = [
+  { id: "protected-paths", pattern: /\bprotected\s*paths?\b/i },
+  { id: "permission-profile", pattern: /\b(trusted-full-access|full[- ]access|permission\s*profile)\b/i },
+  { id: "verify-commands", pattern: /\bverify\s*commands?\b/i },
+  { id: "policy-override", pattern: /\b(ignore|disregard|override|bypass)\b[^.\n]{0,40}\b(rule|policy|instruction|guard|restriction)/i },
+  { id: "secret-handling", pattern: /\b(\.env|auth\.json|api[_ -]?key|secret|credential)/i }
+];
+
+function usage() {
+  console.log(`Usage:
+  piagent-import-instructions [project-path] [--apply]
+
+Folds instruction files written for other agents into AGENTS.md.
+
+  (default)   Dry run. Prints the plan, conflicts, and flagged directives.
+  --apply     Append the imported section to AGENTS.md.
+
+Sources, in precedence order (earlier wins):
+${SOURCES.map((source, index) => `  ${index + 1}. ${source.label}`).join("\n")}
+
+AGENTS.md always outranks every import, so re-running never overwrites
+content you have already reviewed.`);
+}
+
+const args = process.argv.slice(2);
+if (args.includes("-h") || args.includes("--help")) {
+  usage();
+  process.exit(0);
+}
+const apply = args.includes("--apply");
+const positional = args.filter((arg) => !arg.startsWith("--"));
+if (positional.length > 1) {
+  console.error(`Expected at most one project path, received ${positional.length}.`);
+  process.exit(2);
+}
+const projectPath = path.resolve(positional[0] ?? process.cwd());
+if (!fs.existsSync(projectPath)) {
+  console.error(`Project path does not exist: ${projectPath}`);
+  process.exit(2);
+}
+
+function readIfRegularFile(absolute) {
+  const stat = fs.lstatSync(absolute, { throwIfNoEntry: false });
+  if (!stat || !stat.isFile()) return undefined;
+  return fs.readFileSync(absolute, "utf8");
+}
+
+function collect(source) {
+  const absolute = path.join(projectPath, source.rel);
+  if (!fs.existsSync(absolute)) return [];
+  if (source.kind === "file") {
+    const text = readIfRegularFile(absolute);
+    return text === undefined ? [] : [{ origin: source.rel, sourceId: source.id, text }];
+  }
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isDirectory()) return [];
+  return fs.readdirSync(absolute)
+    .filter((name) => source.ext.some((ext) => name.endsWith(ext)))
+    .sort()
+    .map((name) => {
+      const text = readIfRegularFile(path.join(absolute, name));
+      return text === undefined ? undefined : { origin: path.posix.join(source.rel, name), sourceId: source.id, text };
+    })
+    .filter(Boolean);
+}
+
+// A heading is the unit of conflict: two sources describing "Build commands"
+// differently is the case a human needs to see.
+function headings(text) {
+  return text
+    .split("\n")
+    .filter((line) => /^#{1,6}\s+\S/.test(line))
+    .map((line) => line.replace(/^#+\s+/, "").trim().toLowerCase());
+}
+
+const documents = SOURCES.flatMap(collect);
+const agentsPath = path.join(projectPath, "AGENTS.md");
+const agentsText = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf8") : "";
+const alreadyImported = agentsText.includes(IMPORT_HEADING);
+
+const flagged = [];
+for (const document of documents) {
+  for (const line of document.text.split("\n")) {
+    for (const { id, pattern } of SENSITIVE_PATTERNS) {
+      if (pattern.test(line)) flagged.push({ origin: document.origin, rule: id, line: line.trim().slice(0, 200) });
+    }
+  }
+}
+
+const seen = new Map();
+const conflicts = [];
+const agentsHeadings = new Set(headings(agentsText));
+for (const document of documents) {
+  for (const heading of headings(document.text)) {
+    if (agentsHeadings.has(heading)) {
+      conflicts.push({ heading, origin: document.origin, resolution: "AGENTS.md wins" });
+      continue;
+    }
+    if (seen.has(heading)) {
+      conflicts.push({ heading, origin: document.origin, resolution: `${seen.get(heading)} wins` });
+      continue;
+    }
+    seen.set(heading, document.origin);
+  }
+}
+
+function renderImportSection() {
+  const lines = [
+    "",
+    IMPORT_HEADING,
+    "",
+    "Folded in from instruction files written for other agents. Treated as",
+    "reference material: rules here do not change protected paths, permission",
+    "profile, or verify commands unless a maintainer moves them into the",
+    "sections above.",
+    ""
+  ];
+  for (const document of documents) {
+    lines.push(`### From \`${document.origin}\``, "");
+    lines.push(document.text.trimEnd(), "");
+  }
+  return lines.join("\n");
+}
+
+const report = {
+  ok: true,
+  projectPath,
+  sourcesFound: documents.map((document) => document.origin),
+  conflicts,
+  flaggedDirectives: flagged,
+  alreadyImported
+};
+
+if (documents.length === 0) {
+  console.log(JSON.stringify({ ...report, imported: false, reason: "no instruction files from other agents found" }, null, 2));
+  process.exit(0);
+}
+
+if (alreadyImported) {
+  console.log(JSON.stringify({
+    ...report,
+    imported: false,
+    reason: "AGENTS.md already contains an imported section; remove it first to re-import"
+  }, null, 2));
+  process.exit(0);
+}
+
+if (!apply) {
+  console.log(JSON.stringify({
+    ...report,
+    dryRun: true,
+    wouldAppendTo: "AGENTS.md",
+    wouldAppendBytes: Buffer.byteLength(renderImportSection()),
+    next: flagged.length > 0
+      ? "review flaggedDirectives, then re-run with --apply"
+      : "re-run with --apply"
+  }, null, 2));
+  process.exit(0);
+}
+
+fs.writeFileSync(agentsPath, `${agentsText.trimEnd()}\n${renderImportSection()}`);
+
+console.log(JSON.stringify({
+  ...report,
+  imported: true,
+  appendedTo: "AGENTS.md",
+  next: flagged.length > 0
+    ? "review flaggedDirectives; nothing in them has been applied to the profile"
+    : "review AGENTS.md and delete the now-redundant source files when satisfied"
+}, null, 2));

package/scripts/init-project.sh

@@ -0,0 +1,369 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/init-project.sh <project-path> [options]
+
+Options:
+  --profile <name-or-json>       auto | generic | web-frontend | backend-api | be-readonly-fe | fullstack | node-typescript | python | data | devops | mobile | docs | path/to/profile.json
+  --package-source <source>      Pi package source committed into .pi/settings.json
+  --force-profile                Replace existing .pi/piagent-profile.json
+  --force-settings               Replace existing .pi/settings.json
+  --skip-agents                  Do not create AGENTS.md
+  --skip-review-guidelines       Do not create REVIEW_GUIDELINES.md
+  -h, --help
+
+Package source examples:
+  # Exact sources are required here because init writes .pi/settings.json and a capability lock:
+  git:github.com/Vt-mmm/piagent@vX.Y.Z
+  https://github.com/Vt-mmm/piagent/archive/refs/tags/vX.Y.Z.tar.gz
+  npm:@your-scope/platform@x.y.z
+
+Default package source:
+  1. --package-source
+  2. PIAGENT_PACKAGE_SOURCE
+  3. local platform path (warn; do not commit for team)
+USAGE
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ $# -lt 1 ]]; then
+  usage >&2
+  exit 2
+fi
+
+PROJECT_PATH="$1"
+shift
+
+PLATFORM_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PROFILE_INPUT="auto"
+PACKAGE_SOURCE="${PIAGENT_PACKAGE_SOURCE:-}"
+FORCE_PROFILE=false
+FORCE_SETTINGS=false
+SKIP_AGENTS=false
+SKIP_REVIEW=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --profile)
+      if [[ $# -lt 2 ]]; then
+        echo "Missing value for --profile" >&2
+        exit 2
+      fi
+      PROFILE_INPUT="$2"
+      shift 2
+      ;;
+    --package-source)
+      if [[ $# -lt 2 ]]; then
+        echo "Missing value for --package-source" >&2
+        exit 2
+      fi
+      PACKAGE_SOURCE="$2"
+      shift 2
+      ;;
+    --force-profile)
+      FORCE_PROFILE=true
+      shift
+      ;;
+    --force-settings)
+      FORCE_SETTINGS=true
+      shift
+      ;;
+    --skip-agents)
+      SKIP_AGENTS=true
+      shift
+      ;;
+    --skip-review-guidelines)
+      SKIP_REVIEW=true
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ ! -d "$PROJECT_PATH" ]]; then
+  echo "FAIL: project path does not exist: $PROJECT_PATH" >&2
+  exit 1
+fi
+
+PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+
+package_has_any() {
+  local project="$1"
+  local pattern="$2"
+  [[ -f "$project/package.json" ]] && grep -Eiq "$pattern" "$project/package.json"
+}
+
+detect_profile() {
+  local project="$1"
+  local has_package=false
+  local frontend=false
+  local backend=false
+  local data=false
+  local mobile=false
+  local devops=false
+  local infra=false
+  local docs=false
+
+  [[ -f "$project/package.json" ]] && has_package=true
+
+  if [[ -f "$project/pubspec.yaml" ]] || { [[ -d "$project/android" ]] && [[ -d "$project/ios" ]]; }; then
+    mobile=true
+  fi
+
+  if [[ -f "$project/dbt_project.yml" ]] || [[ -f "$project/dvc.yaml" ]] || [[ -d "$project/notebooks" ]] || [[ -d "$project/data" ]]; then
+    data=true
+  fi
+
+  if [[ -f "$project/Dockerfile" ]] || [[ -f "$project/docker-compose.yml" ]] || [[ -f "$project/compose.yml" ]] || [[ -f "$project/compose.yaml" ]] || [[ -d "$project/terraform" ]] || [[ -d "$project/infra" ]] || [[ -d "$project/k8s" ]] || [[ -d "$project/helm" ]]; then
+    infra=true
+    devops=true
+  elif [[ -d "$project/.github/workflows" ]]; then
+    devops=true
+  fi
+
+  if [[ -d "$project/docs" ]] || [[ -f "$project/mkdocs.yml" ]] || [[ -f "$project/mint.json" ]] || [[ -f "$project/docusaurus.config.js" ]]; then
+    docs=true
+  fi
+
+  if [[ "$has_package" == true ]]; then
+    if [[ -d "$project/frontend" ]] || [[ -d "$project/apps/web" ]] || [[ -d "$project/apps/frontend" ]]; then
+      frontend=true
+    fi
+
+    if [[ -d "$project/backend" ]] || [[ -d "$project/apps/api" ]] || [[ -d "$project/apps/server" ]]; then
+      backend=true
+    fi
+
+    if package_has_any "$project" '"(next|react|vite|vue|svelte|astro|@angular/core|remix)"' \
+      || [[ -f "$project/next.config.js" ]] || [[ -f "$project/next.config.mjs" ]] || [[ -f "$project/next.config.ts" ]] \
+      || [[ -f "$project/vite.config.js" ]] || [[ -f "$project/vite.config.ts" ]] \
+      || [[ -d "$project/src/app" ]] || [[ -d "$project/pages" ]] || [[ -d "$project/public" ]]; then
+      frontend=true
+    fi
+
+    if package_has_any "$project" '"(@nestjs|express|fastify|hono|koa|apollo-server|graphql-yoga|prisma|typeorm|sequelize|drizzle-orm)"' \
+      || [[ -f "$project/nest-cli.json" ]] || [[ -d "$project/prisma" ]] || [[ -d "$project/src/server" ]] || [[ -d "$project/src/api" ]]; then
+      backend=true
+    fi
+  fi
+
+  if [[ -f "$project/pom.xml" ]] || [[ -f "$project/build.gradle" ]] || [[ -f "$project/build.gradle.kts" ]] || [[ -d "$project/src/main/java" ]] || [[ -d "$project/src/main/kotlin" ]]; then
+    backend=true
+  fi
+
+  if [[ -f "$project/pyproject.toml" ]] && grep -Eiq "(fastapi|flask|django|litestar|starlite)" "$project/pyproject.toml"; then
+    backend=true
+  fi
+
+  if [[ "$mobile" == true ]]; then
+    printf '%s\n' "mobile"
+  elif [[ "$frontend" == true && "$backend" == true ]]; then
+    printf '%s\n' "fullstack"
+  elif [[ "$frontend" == true ]]; then
+    printf '%s\n' "web-frontend"
+  elif [[ "$backend" == true ]]; then
+    printf '%s\n' "backend-api"
+  elif [[ "$data" == true ]]; then
+    printf '%s\n' "data"
+  elif [[ -f "$project/pyproject.toml" ]]; then
+    printf '%s\n' "python"
+  elif [[ "$has_package" == true && -f "$project/tsconfig.json" ]]; then
+    printf '%s\n' "node-typescript"
+  elif [[ "$infra" == true ]]; then
+    printf '%s\n' "devops"
+  elif [[ "$docs" == true ]]; then
+    printf '%s\n' "docs"
+  elif [[ "$devops" == true ]]; then
+    printf '%s\n' "devops"
+  else
+    printf '%s\n' "generic"
+  fi
+}
+
+resolve_profile_path() {
+  local input="$1"
+  if [[ -f "$input" ]]; then
+    printf '%s\n' "$input"
+    return
+  fi
+
+  local candidate="$PLATFORM_ROOT/adapters/$input/profile.json"
+  if [[ -f "$candidate" ]]; then
+    printf '%s\n' "$candidate"
+    return
+  fi
+
+  echo "FAIL: profile not found: $input" >&2
+  echo "Known default profiles:" >&2
+  find "$PLATFORM_ROOT/adapters" -mindepth 2 -maxdepth 2 -name profile.json -print | sed "s#^$PLATFORM_ROOT/adapters/##; s#/profile.json##" | sort >&2
+  exit 1
+}
+
+resolve_package_source() {
+  if [[ -n "$PACKAGE_SOURCE" ]]; then
+    printf '%s\n' "$PACKAGE_SOURCE"
+    return
+  fi
+
+  local existing_settings="$PROJECT_PATH/.pi/settings.json"
+  if [[ -f "$existing_settings" ]]; then
+    local existing_source
+    existing_source="$(node --input-type=module - "$existing_settings" <<'NODE'
+import fs from "node:fs";
+const settings = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const source = Array.isArray(settings.packages)
+  ? settings.packages.find((item) => typeof item === "string" && item.length > 0)
+  : undefined;
+if (source) process.stdout.write(source);
+NODE
+)"
+    if [[ -n "$existing_source" ]]; then
+      printf '%s\n' "$existing_source"
+      return
+    fi
+  fi
+
+  echo "WARN: No exact package source provided." >&2
+  echo "WARN: .pi/settings.json will use local platform path; do not commit it for team use." >&2
+  printf '%s\n' "$PLATFORM_ROOT"
+}
+
+REQUESTED_PROFILE="$PROFILE_INPUT"
+if [[ "$PROFILE_INPUT" == "auto" ]]; then
+  PROFILE_INPUT="$(detect_profile "$PROJECT_PATH")"
+fi
+
+PROFILE_PATH="$(resolve_profile_path "$PROFILE_INPUT")"
+PACKAGE_SOURCE="$(resolve_package_source)"
+node "$PLATFORM_ROOT/scripts/capability-catalog.mjs" validate-source --package-source "$PACKAGE_SOURCE" >/dev/null
+
+mkdir -p "$PROJECT_PATH/.pi"
+
+if [[ ! -f "$PROJECT_PATH/.mcp.json" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.mcp.json" "$PROJECT_PATH/.mcp.json"
+fi
+
+SETTINGS_PATH="$PROJECT_PATH/.pi/settings.json"
+if [[ "$FORCE_SETTINGS" == true || ! -f "$SETTINGS_PATH" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.pi/settings.json" "$SETTINGS_PATH"
+  node --input-type=module - "$SETTINGS_PATH" "$PACKAGE_SOURCE" <<'NODE'
+import fs from "node:fs";
+const [settingsPath, packageSource] = process.argv.slice(2);
+const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+settings.packages = [packageSource];
+fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+NODE
+else
+  echo "SKIP: .pi/settings.json exists. Use --force-settings to replace."
+fi
+
+PROFILE_TARGET="$PROJECT_PATH/.pi/piagent-profile.json"
+CAPABILITY_LOCK_TARGET="$PROJECT_PATH/.pi/piagent-profile.lock.json"
+if [[ "$FORCE_PROFILE" == true || ! -f "$PROFILE_TARGET" ]]; then
+  apply_profile_args=(
+    "$PLATFORM_ROOT/scripts/capability-catalog.mjs"
+    apply-profile
+    --profile "$PROFILE_PATH"
+    --target "$PROFILE_TARGET"
+    --package-source "$PACKAGE_SOURCE"
+  )
+  if [[ "$FORCE_PROFILE" == true ]]; then
+    apply_profile_args+=(--force)
+  fi
+  node "${apply_profile_args[@]}" >/dev/null
+else
+  echo "SKIP: .pi/piagent-profile.json exists. Use --force-profile to replace."
+  node "$PLATFORM_ROOT/scripts/capability-catalog.mjs" resolve \
+    --profile "$PROFILE_TARGET" \
+    --output "$CAPABILITY_LOCK_TARGET" \
+    --package-source "$PACKAGE_SOURCE" >/dev/null
+fi
+
+if [[ ! -f "$PROJECT_PATH/.pi/mcp.json" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.pi/mcp.json" "$PROJECT_PATH/.pi/mcp.json"
+fi
+
+if [[ ! -f "$PROJECT_PATH/.pi/.gitignore" ]]; then
+  if [[ -f "$PLATFORM_ROOT/templates/project/.pi/gitignore.template" ]]; then
+    cp "$PLATFORM_ROOT/templates/project/.pi/gitignore.template" "$PROJECT_PATH/.pi/.gitignore"
+  else
+    cp "$PLATFORM_ROOT/templates/project/.pi/.gitignore" "$PROJECT_PATH/.pi/.gitignore"
+  fi
+fi
+
+PROJECT_GITIGNORE="$PROJECT_PATH/.gitignore"
+if [[ ! -f "$PROJECT_GITIGNORE" ]]; then
+  : > "$PROJECT_GITIGNORE"
+fi
+if ! grep -F "# Pi Agent Platform runtime" "$PROJECT_GITIGNORE" >/dev/null 2>&1; then
+  {
+    echo
+    echo "# Pi Agent Platform runtime"
+    echo ".pi-subagents/"
+    echo "progress.md"
+  } >> "$PROJECT_GITIGNORE"
+fi
+
+if [[ ! -f "$PROJECT_PATH/.pi/project-context.md" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.pi/project-context.md" "$PROJECT_PATH/.pi/project-context.md"
+fi
+
+if [[ ! -f "$PROJECT_PATH/.pi/context-index.json" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.pi/context-index.json" "$PROJECT_PATH/.pi/context-index.json"
+fi
+
+if [[ ! -f "$PROJECT_PATH/.pi/tech-stack.json" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.pi/tech-stack.json" "$PROJECT_PATH/.pi/tech-stack.json"
+fi
+mkdir -p "$PROJECT_PATH/.pi/tech-context"
+if [[ ! -f "$PROJECT_PATH/.pi/tech-context/README.md" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.pi/tech-context/README.md" "$PROJECT_PATH/.pi/tech-context/README.md"
+fi
+
+mkdir -p "$PROJECT_PATH/.pi/memory"
+if [[ ! -f "$PROJECT_PATH/.pi/memory/memory_summary.md" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.pi/memory/memory_summary.md" "$PROJECT_PATH/.pi/memory/memory_summary.md"
+fi
+if [[ ! -f "$PROJECT_PATH/.pi/memory/MEMORY.md" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/.pi/memory/MEMORY.md" "$PROJECT_PATH/.pi/memory/MEMORY.md"
+fi
+
+if [[ "$SKIP_AGENTS" == false && ! -f "$PROJECT_PATH/AGENTS.md" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/AGENTS.md" "$PROJECT_PATH/AGENTS.md"
+fi
+
+if [[ "$SKIP_REVIEW" == false && ! -f "$PROJECT_PATH/REVIEW_GUIDELINES.md" ]]; then
+  cp "$PLATFORM_ROOT/templates/project/REVIEW_GUIDELINES.md" "$PROJECT_PATH/REVIEW_GUIDELINES.md"
+fi
+
+echo "Project initialized:"
+echo "  project: $PROJECT_PATH"
+echo "  requestedProfile: $REQUESTED_PROFILE"
+echo "  resolvedProfile: $PROFILE_INPUT"
+echo "  profile: $PROFILE_TARGET"
+echo "  capabilityLock: $CAPABILITY_LOCK_TARGET"
+echo "  profileSource: $PROFILE_PATH"
+echo "  packageSource: $PACKAGE_SOURCE"
+echo
+echo "Next:"
+echo "  cd \"$PROJECT_PATH\""
+echo "  pi"
+echo "  /login              # first time only"
+echo "  /onboard-project    # first project-read after model selection"
+echo "  /context-index      # inspect compact project context index"
+echo "  /memory-policy      # inspect project memory policy when needed"