diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..f1a2ebc --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,37 @@ +name: GitHub Pages + +on: + push: + branches: ["main", "master"] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload static launch surface + uses: actions/upload-pages-artifact@v3 + with: + path: public + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index c87014c..d0952da 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ This closes the end-to-end operator story: **detect → route to approval → op ## Quickstart ```bash -git clone https://github.com//agentwall.git +git clone https://github.com/reesepj/agentwall.git cd agentwall npm install npm run build @@ -54,12 +54,25 @@ node dist/cli.js start Default address: `http://127.0.0.1:3000` -Run tests: +Run tests and the live smoke check: ```bash npm test +npm run smoke:local ``` +`npm run smoke:local` expects Agentwall to already be running. Override the target with `AGENTWALL_URL=http://host:port npm run smoke:local`. + +Run the local deploy readiness check: + +```bash +npm run deploy:check +npm run start +AGENTWALL_URL=http://127.0.0.1:3000 npm run smoke:local +``` + +`npm run deploy:check` installs locked dependencies if needed, then runs type-check, build, tests, and high-severity audit before printing the exact start and smoke commands. + ## CLI ```bash @@ -76,6 +89,8 @@ agentwall help This repository includes a practical OSS launch baseline: - CI workflow for lint/build/test/audit (`.github/workflows/ci.yml`) +- GitHub Pages workflow for the static launch surface (`.github/workflows/pages.yml`, publishing `public/`) +- Local deploy readiness script (`npm run deploy:check`, backed by `scripts/deploy.sh`) - Security + contribution community files (`SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`) - Issue + PR templates (`.github/ISSUE_TEMPLATE/*`, `.github/pull_request_template.md`) - Architecture, threat model, and release strategy docs in `docs/` diff --git a/docs/agentwall-portfolio.md b/docs/agentwall-portfolio.md index 989dc6a..605d3ec 100644 --- a/docs/agentwall-portfolio.md +++ b/docs/agentwall-portfolio.md @@ -55,7 +55,7 @@ Prompt safety and static filters are not enough for runtime behavior. Agentwall ## 5) Installation + CLI Story ```bash -git clone https://github.com/your-org/agentwall +git clone https://github.com/reesepj/agentwall.git cd agentwall npm install npm run onboard diff --git a/docs/community-issues-seed.md b/docs/community-issues-seed.md index 07dd046..d46005d 100644 --- a/docs/community-issues-seed.md +++ b/docs/community-issues-seed.md @@ -1,24 +1,122 @@ # Community Issue Seed (First 3) -Use these as initial public issues right after launch. +Use these as initial public issues right after launch. They are intentionally scoped so a maintainer can create them without inventing labels or copy. +## Create all three with GitHub CLI + +Run after GitHub auth is available and the public repo exists. The commands intentionally create temporary body files so they work with stock `gh issue create` and create the non-default labels first. + +```bash +gh label create ui --repo reesepj/agentwall --color "1d76db" --description "Dashboard and browser-facing work" || true +gh label create cli --repo reesepj/agentwall --color "5319e7" --description "Command-line interface work" || true +cat > /tmp/agentwall-issue-1.md <<'EOF' +### Goal +Make the dashboard easier to investigate by filtering decision history without editing code or scanning the whole feed. + +### Scope +- Add query params + UI controls for filtering by `decision`, `riskLevel`, and `plane`. +- Preserve filter state in URL. +- Add tests for server route/state shaping. + +### Acceptance criteria +- Operators can filter dashboard decision data by decision, risk level, and plane. +- Filter state survives page refresh through URL params. +- Tests cover the state shape and at least one filtered view. +EOF + +gh issue create --repo reesepj/agentwall \ + --title "good first issue: add structured decision filters to dashboard" \ + --label "good first issue" --label enhancement --label ui \ + --body-file /tmp/agentwall-issue-1.md + +cat > /tmp/agentwall-issue-2.md <<'EOF' +### Goal +Let operators evaluate many sample action contexts offline before pushing policy changes into a live Agentwall runtime. + +### Scope +- Add `agentwall simulate --input ` to evaluate a batch of contexts offline. +- Output summary table + JSON mode. +- Include docs/example input file. + +### Acceptance criteria +- `agentwall simulate --input examples/simulation-input.json` runs without a live server. +- Output includes decision counts and per-item decision details. +- JSON output mode is stable enough for CI or scripts. +EOF + +gh issue create --repo reesepj/agentwall \ + --title "help wanted: policy rule simulator CLI command" \ + --label "help wanted" --label enhancement --label cli \ + --body-file /tmp/agentwall-issue-2.md + +cat > /tmp/agentwall-issue-3.md <<'EOF' +### Goal +Make Agentwall's detection model easier for new contributors and security reviewers to understand. + +### Scope +- Expand `docs/threat-model.md` with detection-to-mitigation mapping. +- Add examples of false-positive/false-negative handling. +- Link from README under product docs. + +### Acceptance criteria +- Threat model docs include a table mapping detections to mitigations. +- Docs explain at least one false-positive and one false-negative example. +- README links the improved taxonomy section. +EOF + +gh issue create --repo reesepj/agentwall \ + --title "good first issue: detection taxonomy documentation improvements" \ + --label "good first issue" --label documentation \ + --body-file /tmp/agentwall-issue-3.md +``` + + ## 1) good first issue: add structured decision filters to dashboard **Labels:** `good first issue`, `enhancement`, `ui` +### Goal +Make the dashboard easier to investigate by filtering decision history without editing code or scanning the whole feed. + +### Scope - Add query params + UI controls for filtering by `decision`, `riskLevel`, and `plane`. - Preserve filter state in URL. - Add tests for server route/state shaping. +### Acceptance criteria +- Operators can filter dashboard decision data by decision, risk level, and plane. +- Filter state survives page refresh through URL params. +- Tests cover the state shape and at least one filtered view. + + ## 2) help wanted: policy rule simulator CLI command **Labels:** `help wanted`, `enhancement`, `cli` +### Goal +Let operators evaluate many sample action contexts offline before pushing policy changes into a live Agentwall runtime. + +### Scope - Add `agentwall simulate --input ` to evaluate a batch of contexts offline. - Output summary table + JSON mode. - Include docs/example input file. +### Acceptance criteria +- `agentwall simulate --input examples/simulation-input.json` runs without a live server. +- Output includes decision counts and per-item decision details. +- JSON output mode is stable enough for CI or scripts. + + ## 3) good first issue: detection taxonomy documentation improvements **Labels:** `good first issue`, `documentation` +### Goal +Make Agentwall's detection model easier for new contributors and security reviewers to understand. + +### Scope - Expand `docs/threat-model.md` with detection-to-mitigation mapping. - Add examples of false-positive/false-negative handling. - Link from README under product docs. + +### Acceptance criteria +- Threat model docs include a table mapping detections to mitigations. +- Docs explain at least one false-positive and one false-negative example. +- README links the improved taxonomy section. diff --git a/docs/install.md b/docs/install.md index 4c32067..fdc3fc6 100644 --- a/docs/install.md +++ b/docs/install.md @@ -8,7 +8,7 @@ ## Local source install ```bash -git clone https://github.com/your-org/agentwall +git clone https://github.com/reesepj/agentwall.git cd agentwall npm install npm run build @@ -41,12 +41,31 @@ agentwall doctor agentwall start ``` -## Verify health +## Verify health and policy decisions ```bash curl http://127.0.0.1:3000/health +npm run smoke:local ``` +`npm run smoke:local` checks `/health` plus representative allowed and denied `/evaluate` decisions against the running service. Use `AGENTWALL_URL=http://host:port npm run smoke:local` for a non-default target. + +## Local deploy readiness check + +```bash +npm run deploy:check +npm run start +AGENTWALL_URL=http://127.0.0.1:3000 npm run smoke:local +``` + +`npm run deploy:check` runs type-check, build, tests, and high-severity audit from the same repo path. If `node_modules` is missing, it first restores locked dependencies with `npm ci`. + +## GitHub Pages launch surface + +The repo includes `.github/workflows/pages.yml`, which publishes the static `public/` directory on pushes to `main` or `master` and on manual workflow dispatch. + +After the repo is public, enable Pages in GitHub repository settings with source `GitHub Actions`, then run or push the Pages workflow. + ## Uninstall - User-level launcher only: remove `/usr/local/bin/agentwall` diff --git a/docs/launch-readiness-checklist.md b/docs/launch-readiness-checklist.md index 8007115..7ea7e20 100644 --- a/docs/launch-readiness-checklist.md +++ b/docs/launch-readiness-checklist.md @@ -27,19 +27,24 @@ Only true last-mile maintainer/admin steps are left unchecked. ## 4) Adoption readiness - [x] Minimal sample config and policy files are valid. - [x] `npm test` and `npm run build` pass. +- [x] Local deploy readiness path scripted (`npm run deploy:check`) and documented. +- [x] Live runtime smoke path scripted (`npm run smoke:local`) and documented. - [x] Version is set (`0.1.0`) and changelog drafted (`CHANGELOG.md`). - [x] CI automation in place (`.github/workflows/ci.yml`). +- [x] GitHub Pages workflow present for static launch surface (`.github/workflows/pages.yml`). ## 5) Last-mile admin (maintainer-owned) - [ ] Configure GitHub repo description, topics, homepage, and social preview image. -- [ ] Decide canonical public clone URL/org and update README if needed. +- [x] Canonical public clone URL selected and reflected in README (`https://github.com/reesepj/agentwall.git`). +- [ ] Push the launch branch once GitHub auth is available. Current blocker: local GitHub HTTPS auth is unavailable (`fatal: could not read Username for 'https://github.com'`). Exact next command: `gh auth login && git push -u origin launch/agentwall-public-ready`. +- [ ] Enable GitHub Pages source as `GitHub Actions` after the repo is public. If GitHub auth is unavailable locally, run: `gh auth login`, then push this branch and enable Pages from Actions in repository settings. - [ ] Create initial release tag (`v0.1.0`) and attach release notes. - [ ] Publish announcement post (problem, why now, demo, quickstart, roadmap). - [ ] Final external account setup items chosen by the maintainer (public inboxes + service accounts). ## 6) Immediate post-launch guardrails - [ ] Enable notifications/triage routine for issues and security reports. -- [ ] Prepare first three community issues (`good first issue` + `help wanted`). +- [x] Prepare first three community issues (`good first issue` + `help wanted`) in `docs/community-issues-seed.md`, including copy-ready bodies and `gh issue create` commands for when GitHub auth is available. - [ ] Open first public roadmap milestone and label policy. --- diff --git a/package-lock.json b/package-lock.json index 44b9af3..ae196e8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1597,9 +1597,9 @@ } }, "node_modules/brace-expansion": { - "version": "1.1.12", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", - "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", + "version": "1.1.14", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz", + "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==", "dev": true, "license": "MIT", "dependencies": { @@ -2222,9 +2222,9 @@ "license": "BSD-3-Clause" }, "node_modules/fastify": { - "version": "5.8.4", - "resolved": "https://registry.npmjs.org/fastify/-/fastify-5.8.4.tgz", - "integrity": "sha512-sa42J1xylbBAYUWALSBoyXKPDUvM3OoNOibIefA+Oha57FryXKKCZarA1iDntOCWp3O35voZLuDg2mdODXtPzQ==", + "version": "5.8.5", + "resolved": "https://registry.npmjs.org/fastify/-/fastify-5.8.5.tgz", + "integrity": "sha512-Yqptv59pQzPgQUSIm87hMqHJmdkb1+GPxdE6vW6FRyVE9G86mt7rOghitiU4JHRaTyDUk9pfeKmDeu70lAwM4Q==", "funding": [ { "type": "github", @@ -2490,9 +2490,9 @@ "license": "ISC" }, "node_modules/handlebars": { - "version": "4.7.8", - "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.8.tgz", - "integrity": "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==", + "version": "4.7.9", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.9.tgz", + "integrity": "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==", "dev": true, "license": "MIT", "dependencies": { @@ -3826,9 +3826,9 @@ "license": "ISC" }, "node_modules/picomatch": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", - "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz", + "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==", "dev": true, "license": "MIT", "engines": { diff --git a/package.json b/package.json index aeabfa9..9414c42 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,8 @@ "uninstall:system": "bash ./scripts/agentwall-uninstall.sh", "test": "node --experimental-vm-modules node_modules/.bin/jest", "lint": "tsc --noEmit", + "smoke:local": "node scripts/smoke-local.js", + "deploy:check": "bash scripts/deploy.sh", "cli": "node dist/cli.js", "init": "node dist/cli.js init", "doctor": "node dist/cli.js doctor" @@ -23,6 +25,18 @@ "ai-safety" ], "license": "MIT", + "files": [ + "dist/", + "public/", + "examples/", + "scripts/agentwall-install.sh", + "scripts/agentwall-uninstall.sh", + "scripts/deploy.sh", + "README.md", + "CHANGELOG.md", + "LICENSE", + "SECURITY.md" + ], "dependencies": { "fastify": "^5.8.4", "js-yaml": "^4.1.0", diff --git a/scripts/deploy.sh b/scripts/deploy.sh new file mode 100755 index 0000000..19532a1 --- /dev/null +++ b/scripts/deploy.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$ROOT_DIR" + +AGENTWALL_URL="${AGENTWALL_URL:-http://127.0.0.1:3000}" + +if [[ ! -d node_modules ]]; then + echo "node_modules missing; installing locked dependencies with npm ci" + npm ci +fi + +echo "==> Type-checking" +npm run lint + +echo "==> Building" +npm run build + +echo "==> Testing" +npm test -- --runInBand + +echo "==> Auditing high+ vulnerabilities" +npm audit --audit-level=high + +cat < { + console.error(`Agentwall local smoke failed: ${error.message}`); + process.exit(1); +});