peer-ai 1.0.0-next.0

package/dist/pipeline.js

@@ -0,0 +1,265 @@
+// The github-actions stack profile's checks, as the workflow render writes (RFC 0006, section 4).
+// Each tool is a release checked against its published checksum, or an image pinned to its
+// digest, and Semgrep's rules are pinned to a commit. Each job runs one tool on the repository.
+// The same commands run in Peer AI's own CI on every rule's failing and passing examples, so
+// what's proven is what a project runs.
+//
+// Job names never change, since a project makes them required checks: a tool's version or the
+// rules a job covers appear only in its steps.
+import { createHash } from "node:crypto";
+import { PROFILES, profileRulesFor } from "peer-ai-standards";
+export const WORKFLOW_FILE = ".github/workflows/peer-ai-security.yml";
+/** The folder the tools are installed in, on the PATH of the job's later steps. */
+const TOOLS = '"$RUNNER_TEMP/peer-ai-tools"';
+const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
+const UPLOAD = "actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1";
+const GITLEAKS = {
+    version: "8.30.1",
+    url: "https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz",
+    sha256: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb",
+};
+const OSV_SCANNER = {
+    version: "2.6.0",
+    url: "https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_linux_amd64",
+    sha256: "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108",
+};
+export const IMAGES = {
+    zizmor: {
+        name: "ghcr.io/zizmorcore/zizmor",
+        tag: "1.30.1",
+        digest: "sha256:a2eb396d886c053073405c7a980f2139ba2248ec172243cfa3841e57196e8101",
+    },
+    semgrep: {
+        name: "semgrep/semgrep",
+        tag: "1.178.0",
+        digest: "sha256:32e459968daabe7ab86968184a29109b9564aa00392401156f9788452b42786b",
+    },
+    sslyze: {
+        name: "nablac0d3/sslyze",
+        tag: "6.3.1",
+        digest: "sha256:3060ce2f3168cf1d74e5a0989660008052bee645826875122ba7edea95e5b95c",
+    },
+    zap: {
+        name: "ghcr.io/zaproxy/zaproxy",
+        tag: "2.17.0",
+        digest: "sha256:781a2bdaea47324e7bab583e2263f21d257b0aee61ed51521a5be45f5f5081ef",
+    },
+};
+export const imageRef = (image) => `${image.name}:${image.tag}@${image.digest}`;
+/** Semgrep's security rules for the common languages, at one commit, which git checks by its hash. */
+const SEMGREP_RULES = {
+    repository: "https://github.com/semgrep/semgrep-rules",
+    commit: "07135b5255b20ad6c29967215422b1ecc1f03988",
+    folders: ["python", "javascript", "typescript", "go", "java", "ruby", "php", "csharp"].map((language) => `${language}/lang/security`),
+};
+export const JOBS = {
+    secrets: {
+        name: "peer-ai / secrets",
+        tool: `Gitleaks ${GITLEAKS.version}`,
+        install: [
+            `curl -sSfL -o ${TOOLS}/gitleaks.tar.gz ${GITLEAKS.url}`,
+            `echo "${GITLEAKS.sha256}  $RUNNER_TEMP/peer-ai-tools/gitleaks.tar.gz" | sha256sum --check --quiet`,
+            `tar -xzf ${TOOLS}/gitleaks.tar.gz -C ${TOOLS} gitleaks`,
+        ],
+        // A pull request's own commits; every other run, the whole history. A secret already replaced
+        // is recorded in .gitleaksignore, with why.
+        scan: [
+            'if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then',
+            '  gitleaks git --no-banner --redact --verbose --exit-code 1 --log-opts="$BASE_SHA..$HEAD_SHA" .',
+            "else",
+            "  gitleaks git --no-banner --redact --verbose --exit-code 1 .",
+            "fi",
+        ],
+        history: true,
+        env: {
+            BASE_SHA: "${{ github.event.pull_request.base.sha }}",
+            HEAD_SHA: "${{ github.event.pull_request.head.sha }}",
+        },
+    },
+    dependencies: {
+        name: "peer-ai / dependencies",
+        tool: `OSV-Scanner ${OSV_SCANNER.version}`,
+        install: [
+            `curl -sSfL -o ${TOOLS}/osv-scanner ${OSV_SCANNER.url}`,
+            `echo "${OSV_SCANNER.sha256}  $RUNNER_TEMP/peer-ai-tools/osv-scanner" | sha256sum --check --quiet`,
+            `chmod +x ${TOOLS}/osv-scanner`,
+        ],
+        // Exit code 128 means it found nothing it can read: not a vulnerability, but said out loud.
+        scan: [
+            "status=0",
+            "osv-scanner scan source --recursive . || status=$?",
+            'if [ "$status" -eq 128 ]; then',
+            '  echo "::warning::OSV-Scanner found no lockfile or manifest it can read, so no dependency was checked."',
+            'elif [ "$status" -ne 0 ]; then',
+            '  exit "$status"',
+            "fi",
+        ],
+    },
+    workflows: {
+        name: "peer-ai / workflows",
+        tool: `zizmor ${IMAGES.zizmor.tag}`,
+        install: [`docker pull ${imageRef(IMAGES.zizmor)}`],
+        // The whole repository, so actions kept in it are checked as well as the workflows.
+        scan: [`docker run --rm -v "$PWD:/repo:ro" -w /repo ${imageRef(IMAGES.zizmor)} --offline .`],
+    },
+    code: {
+        name: "peer-ai / code",
+        tool: `Semgrep ${IMAGES.semgrep.tag}`,
+        install: [
+            `git init -q ${TOOLS}/semgrep-rules`,
+            `git -C ${TOOLS}/semgrep-rules fetch -q --depth 1 ${SEMGREP_RULES.repository} ${SEMGREP_RULES.commit}`,
+            `git -C ${TOOLS}/semgrep-rules checkout -q FETCH_HEAD`,
+            `docker pull ${imageRef(IMAGES.semgrep)}`,
+        ],
+        scan: [
+            [
+                `docker run --rm -v "$PWD:/src:ro" -v ${TOOLS}/semgrep-rules:/rules:ro -w /src ${imageRef(IMAGES.semgrep)}`,
+                "semgrep scan",
+                ...SEMGREP_RULES.folders.map((folder) => `--config /rules/${folder}`),
+                "--error --metrics off --quiet .",
+            ].join(" "),
+        ],
+    },
+};
+/** A value quoted for the shell, whatever it holds. */
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+/**
+ * The environments' addresses, split into those the pipeline can use and those it can't: an
+ * address that isn't a full http or https URL, or that holds a user name or password, which would
+ * be written into the committed workflow.
+ */
+export function environmentAddresses(config) {
+    const usable = [];
+    const unusable = [];
+    for (const environment of config.environments ?? []) {
+        if (environment.url === undefined)
+            continue;
+        const url = URL.canParse(environment.url) ? new URL(environment.url) : undefined;
+        const fits = url !== undefined && ["http:", "https:"].includes(url.protocol) && url.username === "" && url.password === "";
+        if (!fits) {
+            unusable.push({ id: environment.id, url: environment.url });
+            continue;
+        }
+        usable.push({ id: environment.id, url: url.href, host: url.host, production: environment.production });
+    }
+    return { usable, unusable };
+}
+const isWholeProject = (id) => PROFILES.find((profile) => profile.id === id)?.stacks.length === 0;
+/** The pipeline rules that apply at the project's stage, leaving out the ones it set aside. */
+export function pipelineRules(config) {
+    const setAside = new Set((config.standards?.exceptions ?? []).map((exception) => exception.rule));
+    return profileRulesFor({
+        listed: (config.standards?.profiles ?? []).filter(isWholeProject),
+        stage: config.project.stage ?? "mvp",
+        traits: config.project.traits ?? [],
+    }).filter((rule) => rule.profile === "github-actions" && !setAside.has(rule.id));
+}
+const indent = (lines, by) => lines.map((line) => `${" ".repeat(by)}${line}`);
+/** One job: check out the repository, install the tool, run it. */
+function job(id, script, rules) {
+    return [
+        `  ${id}:`,
+        `    name: ${script.name}`,
+        "    runs-on: ubuntu-latest",
+        "    permissions:",
+        "      contents: read",
+        "    steps:",
+        `      - uses: ${CHECKOUT}`,
+        "        with:",
+        ...(script.history === true ? ["          fetch-depth: 0"] : []),
+        "          persist-credentials: false",
+        `      - name: Install ${script.tool}`,
+        "        run: |",
+        ...indent(['mkdir -p "$RUNNER_TEMP/peer-ai-tools"', 'echo "$RUNNER_TEMP/peer-ai-tools" >> "$GITHUB_PATH"'], 10),
+        ...indent(script.install, 10),
+        `      - name: Check ${rules.join(", ")}`,
+        ...(script.env === undefined
+            ? []
+            : ["        env:", ...Object.entries(script.env).map(([key, value]) => `          ${key}: ${value}`)]),
+        "        run: |",
+        ...indent(script.scan, 10),
+    ];
+}
+const SCHEDULED = "    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'";
+/** The workflow's jobs for the rules that apply, and the environments with usable addresses. */
+function jobs(config) {
+    const rules = pipelineRules(config);
+    const lines = [];
+    for (const id of Object.keys(JOBS)) {
+        const covered = rules.filter((rule) => rule.enforcer?.tool === "github-actions" && rule.enforcer.job === id);
+        if (covered.length > 0)
+            lines.push(...job(id, JOBS[id], covered.map((rule) => rule.id)));
+    }
+    const ids = new Set(rules.map((rule) => rule.id));
+    const { usable } = environmentAddresses(config);
+    if (ids.has("GHA-06") && usable.length > 0) {
+        lines.push("  tls:", "    name: peer-ai / tls", "    runs-on: ubuntu-latest", SCHEDULED, "    permissions: {}", "    steps:", `      - name: Check GHA-06 with SSLyze ${IMAGES.sslyze.tag}, against Mozilla's intermediate profile`, `        run: docker run --rm ${imageRef(IMAGES.sslyze)} --mozilla_config=intermediate ${usable.map((address) => quote(address.host)).join(" ")}`);
+    }
+    // Only an environment the config marks as not production is scanned: one it doesn't mark might be.
+    const staging = usable.filter((address) => address.production === false);
+    if (ids.has("GHA-07") && staging.length > 0) {
+        lines.push("  running-app:", "    name: peer-ai / running-app", "    runs-on: ubuntu-latest", SCHEDULED, "    permissions:", "      contents: read", "    steps:", `      - uses: ${CHECKOUT}`, "        with:", "          persist-credentials: false", "      - name: Prepare the scan, with the accepted findings in .github/zap-rules.tsv", "        run: |", "          mkdir -p zap && chmod 777 zap", "          if [ -f .github/zap-rules.tsv ]; then cp .github/zap-rules.tsv zap/; fi", ...staging.flatMap((address) => [
+            `      - name: Check GHA-07 with OWASP ZAP ${IMAGES.zap.tag} in ${address.id}, which isn't production`,
+            "        run: |",
+            "          if [ -f zap/zap-rules.tsv ]; then set -- -c zap-rules.tsv; fi",
+            `          docker run --rm -v "$PWD/zap:/zap/wrk:rw" ${imageRef(IMAGES.zap)} zap-baseline.py -t ${quote(address.url)} -J ${quote(`zap-${address.id}.json`)} "$@"`,
+        ]), `      - uses: ${UPLOAD}`, "        if: always()", "        with:", "          name: zap-reports", "          path: zap/*.json");
+    }
+    return lines;
+}
+/** The workflow's body, below its header, or undefined when no job applies. */
+export function workflowBody(config) {
+    const body = jobs(config);
+    if (body.length === 0)
+        return undefined;
+    const branch = config.repo?.defaultBranch;
+    return [
+        "name: Peer AI security checks",
+        "on:",
+        "  pull_request:",
+        // With no default branch in the config, changes are checked in their pull requests.
+        ...(branch === undefined ? [] : ["  push:", `    branches: [${branch}]`]),
+        "  schedule:",
+        '    - cron: "23 4 * * *"',
+        "  workflow_dispatch:",
+        "permissions: {}",
+        "jobs:",
+        ...body,
+        "",
+    ].join("\n");
+}
+/** The jobs the workflow render writes would run: the keys under jobs:. */
+export function workflowJobs(config) {
+    return [...(workflowBody(config) ?? "").matchAll(/^ {2}([a-z-]+):$/gm)]
+        .map((match) => match[1] ?? "")
+        .filter((id) => !["pull_request", "push", "schedule", "workflow_dispatch"].includes(id));
+}
+const normalise = (text) => text.replaceAll("\r\n", "\n");
+const hash = (body) => createHash("sha256").update(normalise(body)).digest("hex").slice(0, 16);
+const HASH_LINE = /^# peer-ai sha256: ([0-9a-f]{16})$/m;
+/** The whole file render writes: a header recording the body's hash, then the body. */
+export function workflowFile(config) {
+    const body = workflowBody(config);
+    if (body === undefined)
+        return undefined;
+    return [
+        "# Generated by peer-ai render from peer-ai.config.json: the checks of the github-actions stack profile.",
+        "# Change the config, not this file. Render writes it again while it's as render left it, and leaves",
+        "# it alone once someone changes it by hand. Make each job a required check: their names never change.",
+        `# peer-ai sha256: ${hash(body)}`,
+        body,
+    ].join("\n");
+}
+/** Whether a file was written by render: it records a hash in its header. */
+export const writtenByRender = (content) => HASH_LINE.test(normalise(content));
+/** Whether a file is as render wrote it: its body still has the hash its header records. */
+export function unchangedSinceRender(content) {
+    const text = normalise(content);
+    const recorded = HASH_LINE.exec(text)?.[1];
+    if (recorded === undefined)
+        return false;
+    const body = text.slice(text.indexOf("\n", text.search(HASH_LINE)) + 1);
+    return hash(body) === recorded;
+}
+/** Whether two files are the same apart from their line endings. */
+export const sameFile = (a, b) => normalise(a) === normalise(b);

package/dist/prompter.d.ts

@@ -0,0 +1,23 @@
+export interface Choice<T extends string> {
+    value: T;
+    label: string;
+    hint?: string;
+}
+export interface Prompter {
+    intro(title: string): void;
+    note(message: string, title?: string): void;
+    text(message: string, options?: {
+        initial?: string;
+        placeholder?: string;
+        required?: boolean;
+    }): Promise<string>;
+    select<T extends string>(message: string, choices: Choice<T>[], initial?: T): Promise<T>;
+    multiselect<T extends string>(message: string, choices: Choice<T>[]): Promise<T[]>;
+    confirm(message: string, initial?: boolean): Promise<boolean>;
+    outro(message: string): void;
+}
+/** Thrown when the user cancels a question, so nothing is written. */
+export declare class Cancelled extends Error {
+    constructor();
+}
+export declare function createTerminalPrompter(): Prompter;

package/dist/prompter.js

@@ -0,0 +1,56 @@
+// The questions `init` asks go through this interface, so tests can answer them without a
+// terminal and a future non-terminal front end can too.
+import * as clack from "@clack/prompts";
+/** Thrown when the user cancels a question, so nothing is written. */
+export class Cancelled extends Error {
+    constructor() {
+        super("cancelled");
+    }
+}
+function answer(value) {
+    if (clack.isCancel(value) || typeof value === "symbol")
+        throw new Cancelled();
+    return value;
+}
+function options(choices) {
+    return choices.map((choice) => ({
+        value: choice.value,
+        label: choice.label,
+        ...(choice.hint === undefined ? {} : { hint: choice.hint }),
+    }));
+}
+export function createTerminalPrompter() {
+    return {
+        intro: (title) => {
+            clack.intro(title);
+        },
+        note: (message, title) => {
+            clack.note(message, title);
+        },
+        text: async (message, settings = {}) => {
+            const value = await clack.text({
+                message,
+                ...(settings.placeholder === undefined ? {} : { placeholder: settings.placeholder }),
+                ...(settings.initial === undefined ? {} : { initialValue: settings.initial }),
+                validate: (input) => (settings.required === true && (input ?? "").trim() === "" ? "Required" : undefined),
+            });
+            return answer(value).trim();
+        },
+        select: async (message, choices, initial) => {
+            const value = await clack.select({
+                message,
+                options: options(choices),
+                ...(initial === undefined ? {} : { initialValue: initial }),
+            });
+            return answer(value);
+        },
+        multiselect: async (message, choices) => {
+            const value = await clack.multiselect({ message, options: options(choices), required: false });
+            return answer(value);
+        },
+        confirm: async (message, initial = true) => answer(await clack.confirm({ message, initialValue: initial })),
+        outro: (message) => {
+            clack.outro(message);
+        },
+    };
+}

package/dist/render.d.ts

@@ -0,0 +1,58 @@
+import type { PeerAiConfig, ToolId } from "peer-ai-workflow";
+import type { Output } from "./init.ts";
+export declare const START = "<!-- peer-ai:start -->";
+export declare const END = "<!-- peer-ai:end -->";
+/** What render does to one file. `content` is the whole file to write, when it changes. */
+export interface Planned {
+    path: string;
+    /** kept: a file render owns that someone changed by hand, which render leaves alone on purpose. */
+    action: "create" | "update" | "unchanged" | "refused" | "kept";
+    content?: string;
+    note?: string;
+}
+/** What render does to one skill's folder. */
+export interface PlannedSkill {
+    /** The folder, such as .claude/skills/peer-ai-security-review. */
+    path: string;
+    action: "create" | "update" | "unchanged" | "remove";
+    /** Every file the folder should hold, by its path inside the folder. */
+    files: Map<string, string>;
+    /** Files in the folder that shouldn't be there any more. */
+    stale: string[];
+}
+export interface RenderPlan {
+    files: Planned[];
+    skills: PlannedSkill[];
+    /** Steps render can't take inside the project, such as a tool that keeps servers in the user's own config. */
+    manual: string[];
+}
+/** How AI tools start the server: the project's own pinned copy, or this exact version. */
+export declare function serverCommand(root: string): {
+    command: string;
+    args: string[];
+};
+/**
+ * The command that writes only the skills, for a session or a cloud agent to run before it starts.
+ * It uses the same peer-ai the MCP server does: the project's pinned copy, or this exact version.
+ */
+export declare function skillsCommand(root: string): string;
+/** The instructions every tool gets: short, because the MCP server serves the detail on demand. */
+export declare function instructions(config: PeerAiConfig): string;
+/**
+ * Where the tools in the config read skills. Codex, Cursor, Copilot and Gemini CLI read the shared
+ * .agents/skills; Claude Code reads .claude/skills, which Cursor and Copilot also read. So each
+ * skill is written as few times as the tools allow, and not at all when no tool is listed.
+ */
+export declare function skillFolders(tools: ToolId[]): string[];
+export declare function planRender(root: string, config: PeerAiConfig): RenderPlan;
+export interface RenderOptions {
+    cwd: string;
+    /** Change nothing; fail when a file is out of date. For CI. */
+    check: boolean;
+    /** Write only the skills, touching nothing that's committed. What each tool's setup step runs. */
+    skills?: boolean;
+    /** Print nothing unless something fails. */
+    quiet?: boolean;
+}
+/** Exit code 0 when done or up to date; 1 when a file was refused, or out of date with --check; 2 without a valid config. */
+export declare function runRender(options: RenderOptions, out: Output): number;