forgedock 1.1.1 → 1.1.2

package/examples/forgedock-demo/issues/19-docs-api-reference-full.md

@@ -0,0 +1,53 @@
+---
+title: "docs(api): add complete API reference covering all endpoints"
+labels: ["documentation", "priority:P3"]
+difficulty: "easy"
+---
+
+## Problem
+
+The demo API now has 9 endpoints (health, list, count, tags, get, create, patch,
+delete, and the bulk/archive/restore endpoints added by later issues) but only
+the original 5 are described in issue #5's `docs/API.md` — and issue #5 may not
+have been run yet. Either way, the current baseline has no `docs/API.md`, or an
+incomplete one.
+
+## Proposed Solution
+
+Create (or rewrite) `docs/API.md` documenting all endpoints in the **current
+baseline** (i.e. after the source-code changes in this PR land):
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/health` | no | Liveness check |
+| GET | `/notes` | no | List notes (supports `?where=`, `?tag=`, `?limit=`, `?offset=`) |
+| GET | `/notes/count` | no | Count notes (supports `?owner=`, `?secret=`) |
+| GET | `/notes/tags` | no | List all unique tags |
+| GET | `/notes/:id` | no | Fetch one note |
+| POST | `/notes` | yes | Create a note |
+| PATCH | `/notes/:id` | yes | Update title/body |
+| DELETE | `/notes/:id` | no* | Delete a note |
+
+Include a `curl` example for each endpoint, note the intentional flaws inline
+(e.g. `?where=` is injection-vulnerable — see issue #2), and describe the
+`Authorization: Bearer demo-token` header.
+
+`*` DELETE is intentionally unprotected — document this as a known flaw (issue #1).
+
+## Affected Files
+
+1. `docs/API.md` (NEW or REWRITE) — full endpoint reference.
+2. `README.md` — add a "API reference: docs/API.md" link in the "What's inside"
+   section if not already present.
+
+## Acceptance Criteria
+
+- [ ] `docs/API.md` documents all 8 baseline endpoints with method, path, auth
+  requirement, description, and a `curl` example.
+- [ ] The intentional flaws (injection, missing auth on DELETE) are called out
+  inline with references to the corresponding issue numbers.
+- [ ] `README.md` links to `docs/API.md`.
+- [ ] No code changes required.
+
+> Non-code work that still goes through the full pipeline — investigate the
+> current route surface, write accurate docs, review for completeness.

package/examples/forgedock-demo/issues/20-docs-intentional-flaw-convention.md

@@ -0,0 +1,46 @@
+---
+title: "docs(demo): document the intentional-flaw and graded-issue authoring convention"
+labels: ["documentation", "priority:P3"]
+difficulty: "easy"
+---
+
+## Problem
+
+The demo corpus relies on a deliberate convention — intentional flaws in source
+code, graded issue difficulty, DEMO NOTE comments — but this convention is
+undocumented outside of the source code comments themselves. Someone contributing
+new issues, or using this corpus as a template for their own eval harness, has no
+single reference explaining how the pieces fit together.
+
+## Proposed Solution
+
+Create `docs/CORPUS-AUTHORING.md` that explains:
+
+1. **The intentional-flaw pattern** — why flaws are introduced in baseline
+   source code and how to mark them with `>>> DEMO NOTE:` comments.
+2. **The graded-difficulty taxonomy** — the five categories (bug, feature,
+   refactor, perf, docs) and the three difficulty tiers (easy, medium, hard),
+   with one example per category from this corpus.
+3. **Issue spec format** — the required YAML frontmatter fields (`title`,
+   `labels`, `difficulty`), the required markdown sections (`## Problem`,
+   `## Affected Files`, `## Acceptance Criteria`), and the closing `> ...`
+   callout paragraph.
+4. **Independence constraint** — how to verify that a new issue is resolvable
+   against the baseline commit without depending on other unmerged issues.
+
+## Affected Files
+
+1. `docs/CORPUS-AUTHORING.md` (NEW).
+2. `README.md` — add a link to `docs/CORPUS-AUTHORING.md` in a "Contributing
+   issues" sub-section.
+
+## Acceptance Criteria
+
+- [ ] `docs/CORPUS-AUTHORING.md` covers all four sections listed above.
+- [ ] Each section references at least one existing issue from the corpus as a
+  concrete example.
+- [ ] `README.md` links to the new doc.
+- [ ] No code changes required.
+
+> A meta-doc that makes the demo self-explaining. Useful for anyone wanting to
+> extend the corpus or use it as a template for their own benchmark.

package/examples/forgedock-demo/scripts/smoke.js

@@ -48,8 +48,25 @@ async function main() {
   const unauth = await request(port, 'POST', '/notes', { json: { title: 'nope' } });
   assert.strictEqual(unauth.status, 401, 'POST without token returns 401');
 
+  const count = await request(port, 'GET', '/notes/count');
+  assert.strictEqual(typeof count.body.count, 'number', 'GET /notes/count returns a number');
+
+  const tags = await request(port, 'GET', '/notes/tags');
+  assert.ok(Array.isArray(tags.body.tags), 'GET /notes/tags returns an array');
+
+  const page = await request(port, 'GET', '/notes?limit=1');
+  assert.ok(page.body.notes.length <= 1, 'GET /notes?limit=1 returns at most one note');
+
+  const noteId = created.body.note.id;
+  const patched = await request(port, 'PATCH', `/notes/${noteId}`, {
+    token: 'demo-token',
+    json: { title: 'smoke (patched)' },
+  });
+  assert.strictEqual(patched.status, 200, 'PATCH with token returns 200');
+  assert.strictEqual(patched.body.note.title, 'smoke (patched)', 'PATCH updates the title');
+
   // eslint-disable-next-line no-console
-  console.log('SMOKE OK — health, list, create(auth), create(unauth) all pass');
+  console.log('SMOKE OK — health, list, create(auth), create(unauth), count, tags, pagination, patch all pass');
   server.close();
 }
 

package/examples/forgedock-demo/src/db.js

@@ -10,12 +10,14 @@
 // >>> It exists only inside examples/forgedock-demo so the review agents have
 // >>> something to catch. Do not copy this pattern into real code.
 
-let notes = [
-  { id: 1, owner: 'alice', title: 'Buy milk', body: 'Whole milk, 2 liters', secret: false },
-  { id: 2, owner: 'alice', title: 'Launch plan', body: 'Ship the demo repo', secret: true },
-  { id: 3, owner: 'bob', title: 'Gym', body: 'Leg day', secret: false },
+const SEED = [
+  { id: 1, owner: 'alice', title: 'Buy milk', body: 'Whole milk, 2 liters', secret: false, tags: ['errand'], archived: false, createdAt: '2024-01-01T00:00:00.000Z' },
+  { id: 2, owner: 'alice', title: 'Launch plan', body: 'Ship the demo repo', secret: true, tags: ['work'], archived: false, createdAt: '2024-01-02T00:00:00.000Z' },
+  { id: 3, owner: 'bob', title: 'Gym', body: 'Leg day', secret: false, tags: ['fitness', 'errand'], archived: false, createdAt: '2024-01-03T00:00:00.000Z' },
 ];
 
+let notes = SEED.map((n) => ({ ...n }));
+
 let nextId = 4;
 
 function all() {
@@ -43,7 +45,13 @@ function query(whereClause) {
 }
 
 function insert(note) {
-  const record = { id: nextId++, secret: false, ...note };
+  const record = { id: nextId++, secret: false, tags: [], archived: false, createdAt: new Date().toISOString() };
+  // Only override a default when the caller actually supplied the key — a
+  // spread of an object containing an explicit `undefined` would otherwise
+  // silently clobber the default (e.g. `tags: undefined`).
+  for (const [key, value] of Object.entries(note)) {
+    if (value !== undefined) record[key] = value;
+  }
   notes.push(record);
   return record;
 }
@@ -55,12 +63,29 @@ function remove(id) {
 }
 
 function reset() {
-  notes = [
-    { id: 1, owner: 'alice', title: 'Buy milk', body: 'Whole milk, 2 liters', secret: false },
-    { id: 2, owner: 'alice', title: 'Launch plan', body: 'Ship the demo repo', secret: true },
-    { id: 3, owner: 'bob', title: 'Gym', body: 'Leg day', secret: false },
-  ];
+  notes = SEED.map((n) => ({ ...n }));
   nextId = 4;
 }
 
-module.exports = { all, findById, query, insert, remove, reset };
+// Returns a NEW array sorted by `id` ascending — does not mutate `arr`.
+//
+// >>> DEMO NOTE: bubble sort is an INTENTIONAL, isolated inefficiency (O(n^2))
+// >>> kept here so the review/perf pipeline has a real hot path to optimize.
+// >>> `notes` is already maintained in insertion (id) order, so callers that
+// >>> only need "sorted by id" rarely need this at all — see the perf issue
+// >>> that targets its one caller in routes/notes.js.
+function bubbleSortById(arr) {
+  const copy = arr.slice();
+  for (let i = 0; i < copy.length; i++) {
+    for (let j = 0; j < copy.length - i - 1; j++) {
+      if (copy[j].id > copy[j + 1].id) {
+        const tmp = copy[j];
+        copy[j] = copy[j + 1];
+        copy[j + 1] = tmp;
+      }
+    }
+  }
+  return copy;
+}
+
+module.exports = { all, findById, query, insert, remove, reset, bubbleSortById };

package/examples/forgedock-demo/src/routes/notes.js

@@ -8,17 +8,80 @@ const db = require('../db');
 const { requireToken } = require('../auth');
 
 // GET /notes
-// Lists notes. Supports an optional ?where= filter that is passed straight
-// into db.query().
+// Lists notes. Supports:
+//   ?where=   — raw expression passed straight into db.query() (see db.js)
+//   ?tag=     — exact match against a note's `tags` array
+//   ?limit=, ?offset= — pagination
 //
 // >>> DEMO NOTE: forwarding the raw ?where= string into db.query() is the
 // >>> injection surface (see db.js). Issue #2 asks to make this safe.
 function listNotes(req, res, params) {
-  const where = params.query.where;
-  if (where) {
-    return { notes: db.query(where) };
+  const { where, tag, limit, offset } = params.query;
+
+  let results = where ? db.query(where) : db.all();
+
+  if (tag) {
+    // >>> DEMO NOTE: `tags` is accepted but never validated as an array at
+    // >>> write time (see createNote below). A note created with a
+    // >>> malformed `tags` value makes this `.includes()` call throw instead
+    // >>> of being skipped safely. INTENTIONAL, isolated flaw.
+    results = results.filter((n) => n.tags.includes(tag));
+  }
+
+  if (limit !== undefined || offset !== undefined) {
+    // >>> DEMO NOTE: `offset` is not clamped to a non-negative value, so a
+    // >>> negative offset falls through to Array.prototype.slice's
+    // >>> negative-index semantics (counts from the end) instead of being
+    // >>> rejected or normalized to 0. INTENTIONAL, isolated flaw.
+    const off = Number(offset) || 0;
+    const lim = Number(limit);
+    // Sorting by id here is redundant — `results` is already in id order —
+    // but the demo intentionally uses the O(n^2) helper anyway (see db.js).
+    const sorted = db.bubbleSortById(results);
+    results = sorted.slice(off, Number.isFinite(lim) ? off + lim : undefined);
+  }
+
+  return { notes: results };
+}
+
+// GET /notes/count
+// Returns { count } for notes matching optional ?owner= / ?secret= filters.
+//
+// >>> DEMO NOTE: builds its where-clause with naive string concatenation and
+// >>> reuses the vulnerable db.query() eval path — the same injection class
+// >>> issue #2 asks you to remove from listNotes, but reintroduced here in a
+// >>> sibling endpoint issue #2's scope doesn't touch. INTENTIONAL, isolated
+// >>> flaw kept for the benchmark corpus.
+function countNotes(req, res, params) {
+  const { owner, secret } = params.query;
+  const clauses = [];
+  if (owner) clauses.push('owner === "' + owner + '"');
+  if (secret !== undefined) clauses.push('secret === ' + (secret === 'true'));
+  const whereClause = clauses.length ? clauses.join(' && ') : 'true';
+  return { count: db.query(whereClause).length };
+}
+
+// GET /notes/tags
+// Returns the de-duplicated list of tags across all notes.
+//
+// >>> DEMO NOTE: de-dupes with a nested loop (checks every tag against every
+// >>> unique tag seen so far) instead of a Set — O(n^2) on the total tag
+// >>> count. INTENTIONAL, isolated inefficiency kept for the perf corpus.
+function listTags(req, res, params) {
+  const unique = [];
+  for (const note of db.all()) {
+    for (const t of note.tags || []) {
+      let seen = false;
+      for (const u of unique) {
+        if (u === t) {
+          seen = true;
+          break;
+        }
+      }
+      if (!seen) unique.push(t);
+    }
   }
-  return { notes: db.all() };
+  return { tags: unique };
 }
 
 // GET /notes/:id
@@ -33,19 +96,53 @@ function getNote(req, res, params) {
 }
 
 // POST /notes  (protected)
+//
+// >>> DEMO NOTE: accepts a `tags` field but never checks that it's an array
+// >>> before storing it. A malformed value (e.g. a number) is stored as-is
+// >>> and later crashes GET /notes?tag= (see listNotes). INTENTIONAL,
+// >>> isolated flaw kept for the benchmark corpus.
 function createNote(req, res, params) {
   requireToken(req);
-  const { title, body, owner } = params.body || {};
+  const { title, body, owner, tags } = params.body || {};
   if (!title) {
     const err = new Error('title is required');
     err.statusCode = 400;
     throw err;
   }
-  const note = db.insert({ title, body: body || '', owner: owner || 'anonymous' });
+  const payload = { title, body: body || '', owner: owner || 'anonymous' };
+  if (tags !== undefined) payload.tags = tags;
+  const note = db.insert(payload);
   res.statusCode = 201;
   return { note };
 }
 
+// PATCH /notes/:id  (protected)
+//
+// >>> DEMO NOTE: applies `owner` and `secret` from the request body
+// >>> unconditionally alongside `title`/`body`. Any caller holding the
+// >>> shared demo token can reassign a note's ownership or flip its
+// >>> `secret` flag to false, exposing it via the unauthenticated
+// >>> GET /notes listing. This is a mass-assignment / over-permissive-write
+// >>> flaw, distinct from issue #1's missing-auth-check pattern.
+// >>> INTENTIONAL, isolated flaw kept for the benchmark corpus. Note that
+// >>> `tags` is NOT among the fields this handler updates yet — that gap is
+// >>> a separate, not-yet-built feature.
+function updateNote(req, res, params) {
+  requireToken(req);
+  const note = db.findById(params.id);
+  if (!note) {
+    const err = new Error('Note not found');
+    err.statusCode = 404;
+    throw err;
+  }
+  const { title, body, owner, secret } = params.body || {};
+  if (title !== undefined) note.title = title;
+  if (body !== undefined) note.body = body;
+  if (owner !== undefined) note.owner = owner;
+  if (secret !== undefined) note.secret = secret;
+  return { note };
+}
+
 // DELETE /notes/:id
 //
 // >>> DEMO NOTE: this mutating route is MISSING a requireToken(req) call, so
@@ -61,4 +158,4 @@ function deleteNote(req, res, params) {
   return { deleted: Number(params.id) };
 }
 
-module.exports = { listNotes, getNote, createNote, deleteNote };
+module.exports = { listNotes, countNotes, listTags, getNote, createNote, updateNote, deleteNote };

package/examples/forgedock-demo/src/server.js

@@ -14,7 +14,10 @@ const PORT = process.env.PORT || 3000;
 const TABLE = [
   ['GET', /^\/notes$/, routes.listNotes],
   ['POST', /^\/notes$/, routes.createNote],
+  ['GET', /^\/notes\/count$/, routes.countNotes],
+  ['GET', /^\/notes\/tags$/, routes.listTags],
   ['GET', /^\/notes\/(?<id>\d+)$/, routes.getNote],
+  ['PATCH', /^\/notes\/(?<id>\d+)$/, routes.updateNote],
   ['DELETE', /^\/notes\/(?<id>\d+)$/, routes.deleteNote],
 ];
 
@@ -58,7 +61,7 @@ const server = http.createServer(async (req, res) => {
 
   const [, pattern, handler] = match;
   const groups = url.pathname.match(pattern).groups || {};
-  const body = req.method === 'POST' ? await readBody(req) : {};
+  const body = req.method === 'POST' || req.method === 'PATCH' ? await readBody(req) : {};
 
   try {
     const result = handler(req, res, { ...groups, query, body });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -36,7 +36,9 @@
     "!bin/tests/",
     "commands/",
     "docs/",
+    "!docs/site/.vitepress/",
     "examples/",
+    "packages/protocol/src/",
     "scripts/",
     "templates/",
     "LICENSE",

package/packages/protocol/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RapierCraft Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/protocol/src/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * forge-protocol-conformance — FORGE Annotation Protocol conformance test runner.
+ *
+ * Usage:
+ *   forge-protocol-conformance [fixtures-dir]
+ *   node src/cli.js [fixtures-dir]
+ *
+ * Reads fixtures from the given directory (default: ./fixtures/).
+ * Each fixture is a JSON file with:
+ *   {
+ *     "description": "human-readable test name",
+ *     "input": "comment body string to parse",
+ *     "expect": {
+ *       "type": "INVESTIGATOR",
+ *       "valid": true,
+ *       "sentinelState": "complete",
+ *       "inlineValue": null,
+ *       "fieldChecks": { "Verdict": "CONFIRMED" }  // optional
+ *     }
+ *   }
+ *
+ * Exit code: 0 if all fixtures pass, 1 if any fail.
+ *
+ * @license MIT
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve, extname } from 'node:path';
+import { parse } from './parse.js';
+import { validate } from './validate.js';
+
+const fixturesDir = resolve(process.argv[2] ?? 'fixtures');
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+let files;
+try {
+  files = readdirSync(fixturesDir).filter(f => extname(f) === '.json').sort();
+} catch (err) {
+  console.error(`Cannot read fixtures directory: ${fixturesDir}`);
+  console.error(err.message);
+  process.exit(1);
+}
+
+if (files.length === 0) {
+  console.error(`No .json fixtures found in ${fixturesDir}`);
+  process.exit(1);
+}
+
+for (const file of files) {
+  const fixturePath = resolve(fixturesDir, file);
+  let fixture;
+  try {
+    fixture = JSON.parse(readFileSync(fixturePath, 'utf8'));
+  } catch (err) {
+    console.error(`SKIP  ${file} — cannot parse JSON: ${err.message}`);
+    continue;
+  }
+
+  const { description, input, expect: expected } = fixture;
+  const label = `${file}: ${description ?? '(no description)'}`;
+
+  if (typeof input !== 'string') {
+    console.error(`SKIP  ${label} — "input" must be a string`);
+    continue;
+  }
+
+  const annotations = parse(input);
+
+  // Find the annotation matching the expected type
+  const ann = annotations.find(a => a.type === expected.type);
+
+  const fixtureErrors = [];
+
+  if (!ann) {
+    fixtureErrors.push(`Expected annotation type "${expected.type}" not found in parsed output`);
+  } else {
+    // Sentinel state check
+    if (expected.sentinelState !== undefined && ann.sentinelState !== expected.sentinelState) {
+      fixtureErrors.push(
+        `sentinelState: expected "${expected.sentinelState}", got "${ann.sentinelState}"`,
+      );
+    }
+
+    // Inline value check
+    if ('inlineValue' in expected) {
+      if (ann.inlineValue !== expected.inlineValue) {
+        fixtureErrors.push(
+          `inlineValue: expected ${JSON.stringify(expected.inlineValue)}, got ${JSON.stringify(ann.inlineValue)}`,
+        );
+      }
+    }
+
+    // Field checks
+    if (expected.fieldChecks) {
+      for (const [key, val] of Object.entries(expected.fieldChecks)) {
+        if (ann.fields[key] !== val) {
+          fixtureErrors.push(
+            `field "${key}": expected "${val}", got "${ann.fields[key] ?? '(missing)'}"`,
+          );
+        }
+      }
+    }
+
+    // validate() result check
+    const { valid, errors } = validate(ann);
+    if (expected.valid === true && !valid) {
+      fixtureErrors.push(`Expected valid=true but got errors: ${errors.join('; ')}`);
+    } else if (expected.valid === false && valid) {
+      fixtureErrors.push(`Expected valid=false but annotation passed validation`);
+    }
+  }
+
+  if (fixtureErrors.length === 0) {
+    console.log(`ok    ${label}`);
+    passed++;
+  } else {
+    console.log(`FAIL  ${label}`);
+    for (const e of fixtureErrors) {
+      console.log(`        ${e}`);
+    }
+    failures.push(label);
+    failed++;
+  }
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed (${files.length} fixtures total)`);
+
+if (failed > 0) {
+  process.exit(1);
+}