@lnilluv/pi-ralph-loop 0.1.3 → 0.1.4-dev.1

package/src/secret-paths.ts

@@ -0,0 +1,66 @@
+import { basename, normalize, relative, resolve } from "node:path";
+import { minimatch } from "minimatch";
+
+const SECRET_PATH_SEGMENTS = new Set([".aws", ".ssh", "secrets", "credentials", "ops-secrets", "credentials-prod"]);
+const SECRET_BASENAMES = new Set([".npmrc", ".pypirc", ".netrc"]);
+const SECRET_SUFFIXES = [".pem", ".key", ".asc"];
+export const SECRET_PATH_POLICY_TOKEN = "policy:secret-bearing-paths";
+
+function toPosixPath(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+function normalizePath(value: string): string {
+  return toPosixPath(normalize(value));
+}
+
+function candidatePaths(path: string, cwd?: string): string[] {
+  const candidates = new Set<string>();
+  const normalizedRaw = normalizePath(path);
+  if (normalizedRaw) candidates.add(normalizedRaw);
+
+  const absolutePath = normalizePath(resolve(cwd ?? process.cwd(), path));
+  if (absolutePath) candidates.add(absolutePath);
+
+  if (cwd) {
+    const repoRelative = toPosixPath(relative(cwd, absolutePath));
+    if (repoRelative && !repoRelative.startsWith("..")) candidates.add(repoRelative);
+  }
+
+  return [...candidates];
+}
+
+function isSecretPathCandidate(candidatePath: string): boolean {
+  const normalizedPath = toPosixPath(candidatePath).toLowerCase();
+  if (!normalizedPath || normalizedPath.startsWith("..")) return false;
+
+  const segments = normalizedPath.split("/").filter(Boolean);
+  const normalizedName = basename(normalizedPath);
+  return (
+    normalizedName.startsWith(".env") ||
+    SECRET_BASENAMES.has(normalizedName) ||
+    SECRET_SUFFIXES.some((suffix) => normalizedName.endsWith(suffix)) ||
+    segments.some((segment) => SECRET_PATH_SEGMENTS.has(segment))
+  );
+}
+
+export function isSecretBearingPath(relativePath: string): boolean {
+  return isSecretPathCandidate(normalizePath(relativePath));
+}
+
+export function matchesProtectedPath(relativePath: string, protectedFiles: string[], cwd?: string): boolean {
+  const candidates = candidatePaths(relativePath, cwd);
+  return protectedFiles.some((pattern) =>
+    candidates.some((candidate) =>
+      pattern === SECRET_PATH_POLICY_TOKEN ? isSecretPathCandidate(candidate) : minimatch(candidate, pattern, { matchBase: true }),
+    ),
+  );
+}
+
+export function isSecretBearingTopLevelName(name: string): boolean {
+  return isSecretBearingPath(name);
+}
+
+export function filterSecretBearingTopLevelNames(names: string[]): string[] {
+  return names.filter((name) => !isSecretBearingTopLevelName(name));
+}

package/src/shims.d.ts

@@ -0,0 +1,23 @@
+declare module "yaml" {
+  export function parse(input: string): any;
+}
+
+declare module "minimatch" {
+  export function minimatch(path: string, pattern: string, options?: any): boolean;
+}
+
+declare module "node:fs" {
+  export function readFileSync(path: string, encoding: string): string;
+  export function existsSync(path: string): boolean;
+}
+
+declare module "node:path" {
+  export function resolve(...paths: string[]): string;
+  export function join(...paths: string[]): string;
+  export function dirname(path: string): string;
+  export function basename(path: string): string;
+}
+
+declare module "@mariozechner/pi-coding-agent" {
+  export type ExtensionAPI = any;
+}

package/tests/fixtures/parity/migrate/OPEN_QUESTIONS.md

@@ -0,0 +1,3 @@
+# Open Questions
+
+All clear.

package/tests/fixtures/parity/migrate/RALPH.md

@@ -0,0 +1,27 @@
+---
+commands:
+  - name: legacy
+    run: ./scripts/show-legacy.sh
+    timeout: 20
+  - name: verify
+    run: ./scripts/verify.sh
+    timeout: 20
+required_outputs:
+  - MIGRATED.md
+  - MIGRATION_NOTES.md
+max_iterations: 2
+timeout: 300
+completion_promise: DONE
+guardrails:
+  block_commands: []
+  protected_files: []
+---
+You are migrating a deterministic legacy task into a checked-in summary.
+
+Use only the checked-in legacy files under `legacy/`.
+Do not browse the network.
+
+First, inspect `{{ commands.legacy }}`.
+Then write `MIGRATED.md` so it matches `golden/MIGRATED.md` exactly.
+Write `MIGRATION_NOTES.md` with short bullets that mention `legacy/source.md`, `legacy/source.yaml`, `scripts/show-legacy.sh`, `scripts/verify.sh`, and `golden/MIGRATED.md`.
+Before finishing, run `{{ commands.verify }}`. If the verifier passes and the required outputs exist, clear `OPEN_QUESTIONS.md` of any P0/P1 items and emit <promise>DONE</promise>.

package/tests/fixtures/parity/migrate/golden/MIGRATED.md

@@ -0,0 +1,15 @@
+# Migrated Task
+
+This task was migrated from the checked-in legacy sources.
+
+Sources:
+- legacy/source.md
+- legacy/source.yaml
+
+Checked-in helpers:
+- scripts/show-legacy.sh
+- scripts/verify.sh
+
+Expected outputs:
+- MIGRATED.md
+- MIGRATION_NOTES.md

package/tests/fixtures/parity/migrate/legacy/source.md

@@ -0,0 +1,6 @@
+# Legacy Migration Source
+
+- target: MIGRATED.md
+- helper: scripts/show-legacy.sh
+- verifier: scripts/verify.sh
+- notes: MIGRATION_NOTES.md

package/tests/fixtures/parity/migrate/legacy/source.yaml

@@ -0,0 +1,3 @@
+title: Legacy Migration Source
+output: MIGRATED.md
+notes: MIGRATION_NOTES.md

package/tests/fixtures/parity/migrate/scripts/show-legacy.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+export LC_ALL=C
+
+for file in legacy/source.md legacy/source.yaml; do
+  printf '## %s\n' "$file"
+  cat "$file"
+  printf '\n'
+done

package/tests/fixtures/parity/migrate/scripts/verify.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+export LC_ALL=C
+
+cmp -s golden/MIGRATED.md MIGRATED.md
+
+grep -Fq 'legacy/source.md' MIGRATION_NOTES.md
+grep -Fq 'legacy/source.yaml' MIGRATION_NOTES.md
+grep -Fq 'scripts/show-legacy.sh' MIGRATION_NOTES.md
+grep -Fq 'scripts/verify.sh' MIGRATION_NOTES.md
+grep -Fq 'golden/MIGRATED.md' MIGRATION_NOTES.md
+
+test -s MIGRATED.md
+test -s MIGRATION_NOTES.md

package/tests/fixtures/parity/research/OPEN_QUESTIONS.md

@@ -0,0 +1,3 @@
+# Open Questions
+
+All clear.

package/tests/fixtures/parity/research/RALPH.md

@@ -0,0 +1,45 @@
+---
+commands:
+  - name: snapshots
+    run: ./scripts/show-snapshots.sh
+    timeout: 20
+  - name: verify
+    run: ./scripts/verify.sh
+    timeout: 20
+required_outputs:
+  - evidence/raw/docs-factory-ai-cli-features-missions.md
+  - evidence/raw/factory-ai-news-missions.md
+  - evidence/raw/app-factory-ai-cli.md
+  - INSTALL_FLOW.md
+  - MISSIONS_FINDINGS.md
+  - evidence/INDEX.md
+max_iterations: 2
+timeout: 300
+completion_promise: DONE
+guardrails:
+  block_commands: []
+  protected_files: []
+---
+You are doing a frozen research pass on the Factory.ai public surface.
+
+Use only the checked-in snapshot files under `snapshots/` and the checked-in metadata files in this fixture.
+Do not fetch network content and do not rely on live docs.
+
+The snapshot files are:
+- `snapshots/docs-factory-ai-cli-features-missions.md`
+- `snapshots/factory-ai-news-missions.md`
+- `snapshots/app-factory-ai-cli.md`
+
+The checked-in metadata files are:
+- `source-manifest.md`
+- `claim-evidence-checklist.md`
+- `expected-outputs.md`
+
+First, inspect `./scripts/show-snapshots.sh`.
+Then review the metadata files above.
+Then copy each snapshot verbatim into `evidence/raw/` with the same file name.
+Write `INSTALL_FLOW.md` with the installer path and a short explanation of the public claims.
+Write `MISSIONS_FINDINGS.md` with citations that point at the snapshot file paths.
+Write `evidence/INDEX.md` that maps each raw evidence file back to its source snapshot.
+
+Before you finish, run `./scripts/verify.sh`. If the verifier passes and the required outputs exist, clear `OPEN_QUESTIONS.md` of any P0/P1 items and emit <promise>DONE</promise>.

package/tests/fixtures/parity/research/claim-evidence-checklist.md

@@ -0,0 +1,15 @@
+# Research Claim / Evidence Checklist
+
+Use this checklist to keep every public-surface claim tied to a frozen snapshot.
+
+- [x] The app landing page exposes the install command. Evidence: `snapshots/app-factory-ai-cli.md`
+- [x] The app landing page links out to Missions and the news post. Evidence: `snapshots/app-factory-ai-cli.md`
+- [x] Missions is presented as the guided CLI workflow. Evidence: `snapshots/docs-factory-ai-cli-features-missions.md`
+- [x] The installer surface points at the public npm install path. Evidence: `snapshots/docs-factory-ai-cli-features-missions.md`
+- [x] The news post frames Missions as a launch announcement. Evidence: `snapshots/factory-ai-news-missions.md`
+- [x] The news post repeats the same public installer language. Evidence: `snapshots/factory-ai-news-missions.md`
+- [ ] `INSTALL_FLOW.md` must synthesize the shared installer claim across all three snapshots.
+- [ ] `MISSIONS_FINDINGS.md` must cite each snapshot path directly.
+- [ ] `evidence/INDEX.md` must map each raw evidence file back to its snapshot.
+
+Each output should cite the exact snapshot path used for the claim.

package/tests/fixtures/parity/research/expected-outputs.md

@@ -0,0 +1,22 @@
+# Expected Outputs
+
+The research pass must produce these files in the task workspace.
+
+## Required outputs
+
+- `INSTALL_FLOW.md`
+- `MISSIONS_FINDINGS.md`
+- `evidence/INDEX.md`
+- `OPEN_QUESTIONS.md`
+
+## Required raw evidence copies
+
+- `evidence/raw/app-factory-ai-cli.md`
+- `evidence/raw/docs-factory-ai-cli-features-missions.md`
+- `evidence/raw/factory-ai-news-missions.md`
+
+## Completion criteria
+
+- Copy each snapshot verbatim into `evidence/raw/`.
+- Cite the snapshot paths in `MISSIONS_FINDINGS.md`.
+- Keep `OPEN_QUESTIONS.md` free of P0/P1 items.

package/tests/fixtures/parity/research/scripts/show-snapshots.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+export LC_ALL=C
+
+for file in \
+  snapshots/app-factory-ai-cli.md \
+  snapshots/docs-factory-ai-cli-features-missions.md \
+  snapshots/factory-ai-news-missions.md; do
+  printf '## %s\n' "$file"
+  cat "$file"
+  printf '\n'
+done

package/tests/fixtures/parity/research/scripts/verify.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+export LC_ALL=C
+
+snapshots=(
+  snapshots/app-factory-ai-cli.md
+  snapshots/docs-factory-ai-cli-features-missions.md
+  snapshots/factory-ai-news-missions.md
+)
+raws=(
+  evidence/raw/app-factory-ai-cli.md
+  evidence/raw/docs-factory-ai-cli-features-missions.md
+  evidence/raw/factory-ai-news-missions.md
+)
+
+for index in "${!snapshots[@]}"; do
+  file="${snapshots[$index]}"
+  raw="${raws[$index]}"
+  test -f "$raw"
+  cmp -s "$file" "$raw"
+done
+
+for required in \
+  INSTALL_FLOW.md \
+  MISSIONS_FINDINGS.md \
+  evidence/INDEX.md \
+  OPEN_QUESTIONS.md \
+  source-manifest.md \
+  claim-evidence-checklist.md \
+  expected-outputs.md; do
+  test -s "$required"
+done
+
+for snapshot in "${snapshots[@]}"; do
+  grep -Fq "$snapshot" MISSIONS_FINDINGS.md
+  grep -Fq "$snapshot" claim-evidence-checklist.md
+done
+
+for raw in "${raws[@]}"; do
+  grep -Fq "$raw" evidence/INDEX.md
+  grep -Fq "$raw" expected-outputs.md
+done
+
+for source in \
+  snapshots/app-factory-ai-cli.md \
+  snapshots/docs-factory-ai-cli-features-missions.md \
+  snapshots/factory-ai-news-missions.md \
+  scripts/show-snapshots.sh \
+  scripts/verify.sh; do
+  grep -Fq "$source" source-manifest.md
+done
+
+grep -Fq 'Factory.ai' INSTALL_FLOW.md
+! grep -Eq '(^|[^A-Z0-9])P[01]([^A-Z0-9]|$)' OPEN_QUESTIONS.md

package/tests/fixtures/parity/research/snapshots/app-factory-ai-cli.md

@@ -0,0 +1,11 @@
+# app.factory.ai/cli
+
+Frozen snapshot for parity testing.
+
+## Public-surface claims
+- The app landing page exposes the install command.
+- It links out to Missions and the news post.
+- It is the canonical app-facing public surface for this task.
+
+## Static note
+This file is checked in and must not be refreshed from live docs.

package/tests/fixtures/parity/research/snapshots/docs-factory-ai-cli-features-missions.md

@@ -0,0 +1,11 @@
+# Factory.ai CLI Features — Missions
+
+Frozen snapshot for parity testing.
+
+## Public-surface claims
+- Missions is presented as the guided CLI workflow.
+- The installer surface points at the public npm install path.
+- The page directs readers to the app CLI entrypoint and the news announcement.
+
+## Static note
+This file is checked in and must not be refreshed from live docs.

package/tests/fixtures/parity/research/snapshots/factory-ai-news-missions.md

@@ -0,0 +1,11 @@
+# Factory.ai News — Missions
+
+Frozen snapshot for parity testing.
+
+## Public-surface claims
+- The news post frames Missions as a launch announcement.
+- The wording repeats the same public installer language as the CLI feature page.
+- It is a separate source that should be cited independently.
+
+## Static note
+This file is checked in and must not be refreshed from live docs.

package/tests/fixtures/parity/research/source-manifest.md

@@ -0,0 +1,20 @@
+# Research Source Manifest
+
+Frozen sources for the Factory.ai research fixture.
+
+## Checked-in snapshot sources
+
+| Path | SHA-256 | Purpose |
+| --- | --- | --- |
+| `snapshots/app-factory-ai-cli.md` | `2e05c955f02a7f363cb34eab1bd16a2c35e0aee8d720fb7d15eec9b926c7bb95` | Canonical app-facing public surface |
+| `snapshots/docs-factory-ai-cli-features-missions.md` | `588ca106d5d2ea42f908745c39d517594f6c61e0fe8cd3b8660257aab5002b75` | CLI feature page and Missions guidance |
+| `snapshots/factory-ai-news-missions.md` | `8cdfbe84f96c1521f114172204f7be41b64b24dea6c90e15be3f2a279a3b0cfc` | Launch announcement / independent citation |
+
+## Checked-in helper scripts
+
+| Path | SHA-256 | Purpose |
+| --- | --- | --- |
+| `scripts/show-snapshots.sh` | `ec99441bb5a0835e350908c0fb3425fe8a7a9d625dd71b844a522b4f05f4f957` | Prints the frozen snapshots verbatim |
+| `scripts/verify.sh` | `d21efc8a8c57bff1a3f0302d18aa0515868418c1d5bb4e55aa6f4082a8919dfd` | Verifies the frozen fixture outputs |
+
+These files are the immutable inputs for the research pass. Refreshing them from live docs would break the fixture.