forgedock 1.0.16 → 1.0.18

package/README.md

@@ -6,7 +6,7 @@
 
 <p><strong>Autonomous software development for Claude Code.</strong></p>
 
-<p>A sub-agent orchestration layer with a deterministic pipeline that converts developer intent into structured GitHub issues, giving each agent a tightly scoped prompt with GitHub as its secondary context layer. Builds, fixes, researches, and ships end-to-end with a strict code quality bar that raises the baseline of your entire codebase over time. Fewer tokens, less time, better software. Built for production systems and security from the ground up. Benchmarked across 20,000+ GitHub issues on production codebases.</p>
+<p>ForgeDock turns every bug found, every fix shipped, and every review finding into structured context that makes the next agent smarter. It catches integration bugs that code review can't see — missing route registrations, env vars present in CI but absent in deploy, Docker permission mismatches, sibling code paths left unfixed. Every finding feeds back as a prevention rule for future builds. After thousands of issues on production codebases, the system catches bugs before they reach a testing branch.</p>
 
 <a href="https://www.npmjs.com/package/forgedock"><img src="https://img.shields.io/npm/dm/forgedock?label=npm%20downloads&style=flat-square&color=CB3837" alt="npm downloads/month" /></a>&nbsp;
 <a href="https://www.npmjs.com/package/forgedock"><img src="https://img.shields.io/npm/v/forgedock?style=flat-square&color=CB3837" alt="npm version" /></a>&nbsp;
@@ -95,7 +95,13 @@ The context phase surfaced two historical bugs (#577, #587) in the same module
 
 ## Install
 
-**Requirements:** [Node.js 18+](https://nodejs.org/) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+**Requirements:** [Node.js 18+](https://nodejs.org/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [GitHub CLI (`gh`)](https://cli.github.com/), [`yq`](https://github.com/mikefarah/yq) (YAML parser used by pipeline commands to read `forge.yaml`), and **[Playwright MCP](https://github.com/microsoft/playwright-mcp)** (browser automation for `/qa-sweep` and visual testing commands)
+
+> **Playwright MCP** is a guaranteed ForgeDock dependency for browser automation commands. Register it in Claude Code after installing ForgeDock:
+> ```bash
+> claude mcp add playwright npx @playwright/mcp@latest
+> ```
+> Verify with `npx forgedock doctor` — Check 9 confirms Playwright MCP is registered.
 
 ```bash
 # Install pipeline commands
@@ -132,6 +138,33 @@ npx forgedock help         # Show all available commands
 
 ---
 
+## Global Command Namespace
+
+ForgeDock owns the **global** `~/.claude/commands/` namespace. When `npx forgedock` runs, it symlinks all pipeline commands there and writes a `.symlink-source` sentinel file so other installers can detect the owner:
+
+```
+~/.claude/commands/
+  .symlink-source       ← sentinel: "ForgeDock owns this namespace"
+  work-on.md            → /path/to/forgedock/commands/work-on.md
+  review-pr.md          → /path/to/forgedock/commands/review-pr.md
+  ...
+```
+
+**Project-specific commands** should install to the **project-local** `.claude/commands/` directory instead:
+
+```
+your-project/
+  .claude/
+    commands/
+      my-custom-command.md   ← project-local — Claude Code merges these in
+```
+
+Claude Code merges global (`~/.claude/commands/`) and project-local (`.claude/commands/`) automatically. Project-local commands win on name collisions.
+
+If another tool runs its own install script that targets `~/.claude/commands/`, it will silently repoint ForgeDock's symlinks to its own source path — breaking all ForgeDock commands globally. The `.symlink-source` sentinel is a machine-readable warning to other installers; ForgeDock also emits a per-command warning during `npx forgedock install` when it detects a collision.
+
+---
+
 ## How It Works
 
 ```
@@ -200,13 +233,31 @@ Removes all ForgeDock command symlinks from `~/.claude/commands/`. Your `forge.y
 
 ---
 
+## Star History
+
+<a href="https://star-history.com/#RapierCraftStudios/ForgeDock&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date" />
+ </picture>
+</a>
+
+---
+
 ## Contributing
 
 PRs welcome. Every change goes through a PR, tested against 3+ scenarios, using conventional commits (`fix(command):`, `feat(command):`, `refactor(command):`).
 
 ## License
 
-[AGPL-3.0](LICENSE) — free to use, modify, and distribute. If you modify ForgeDock and offer it as a service, you must open-source your modifications under the same license.
+ForgeDock uses a **dual-licensing model**:
+
+- **[AGPL-3.0](LICENSE)** — free to use, modify, and distribute for open-source and personal use. If you modify ForgeDock and offer it as a service (including over a network), you must open-source your modifications under AGPL-3.0.
+
+- **[Commercial License](COMMERCIAL-LICENSE.md)** — for organizations that need to use ForgeDock in proprietary workflows or products without AGPL-3.0 copyleft obligations. [Contact RapierCraft Studios](mailto:licensing@rapiercraft.studio) to obtain a commercial license.
+
+The open-source core remains free under AGPL-3.0. The commercial license is an exception for customers who cannot meet the copyleft requirements.
 
 ---
 

package/bin/cross-publish.mjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+/**
+ * cross-publish.mjs
+ *
+ * Publishes draft articles from docs/articles/ to dev.to and Hashnode.
+ * Reads frontmatter from each .md file. If `published: false`, calls both APIs.
+ * Updates frontmatter to `published: true` and writes to content/publish-log.json.
+ *
+ * Required env vars:
+ *   DEVTO_API_KEY            — dev.to API key (repository secret)
+ *   HASHNODE_ACCESS_TOKEN    — Hashnode personal access token (repository secret)
+ *   HASHNODE_PUBLICATION_ID  — Hashnode publication ID (repository secret)
+ *
+ * Usage:
+ *   node bin/cross-publish.mjs
+ */
+
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..');
+const ARTICLES_DIR = join(REPO_ROOT, 'docs', 'articles');
+const PUBLISH_LOG = join(REPO_ROOT, 'content', 'publish-log.json');
+
+const DEVTO_API_KEY = process.env.DEVTO_API_KEY;
+const HASHNODE_ACCESS_TOKEN = process.env.HASHNODE_ACCESS_TOKEN;
+const HASHNODE_PUBLICATION_ID = process.env.HASHNODE_PUBLICATION_ID;
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse YAML frontmatter from a markdown file body.
+ * Returns { frontmatter: Record<string,string|boolean|string[]>, body: string }.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const raw = match[1];
+  const body = match[2];
+  const frontmatter = {};
+
+  for (const line of raw.split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const val = line.slice(colonIdx + 1).trim();
+
+    if (val === 'true') {
+      frontmatter[key] = true;
+    } else if (val === 'false') {
+      frontmatter[key] = false;
+    } else if (val.startsWith('[') && val.endsWith(']')) {
+      // Simple array: ["a", "b", "c"]
+      frontmatter[key] = val
+        .slice(1, -1)
+        .split(',')
+        .map(s => s.trim().replace(/^["']|["']$/g, ''))
+        .filter(Boolean);
+    } else {
+      // Strip surrounding quotes if present
+      frontmatter[key] = val.replace(/^["']|["']$/g, '');
+    }
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Serialize frontmatter back to YAML block. Sets published: true.
+ */
+function serializeFrontmatter(frontmatter, body) {
+  const lines = [];
+  for (const [key, val] of Object.entries(frontmatter)) {
+    if (typeof val === 'boolean') {
+      lines.push(`${key}: ${val}`);
+    } else if (Array.isArray(val)) {
+      lines.push(`${key}: [${val.map(v => `"${v}"`).join(', ')}]`);
+    } else {
+      lines.push(`${key}: ${val}`);
+    }
+  }
+  return `---\n${lines.join('\n')}\n---\n${body}`;
+}
+
+// ---------------------------------------------------------------------------
+// dev.to publisher
+// ---------------------------------------------------------------------------
+
+async function publishToDevTo(article) {
+  const { title, description, tags, canonical_url, body, markdown } = article;
+
+  const payload = {
+    article: {
+      title,
+      body_markdown: markdown,
+      published: true,
+      tags: Array.isArray(tags) ? tags : [],
+      canonical_url: canonical_url || undefined,
+      description: description || undefined,
+    },
+  };
+
+  console.log(`[dev.to] Publishing: "${title}"`);
+
+  const response = await fetch('https://dev.to/api/articles', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'api-key': DEVTO_API_KEY,
+    },
+    body: JSON.stringify(payload),
+  });
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    const errorMsg = data?.error || JSON.stringify(data);
+    throw new Error(`dev.to API error ${response.status}: ${errorMsg}`);
+  }
+
+  if (!data.id) {
+    throw new Error(`dev.to API returned unexpected response: ${JSON.stringify(data)}`);
+  }
+
+  console.log(`[dev.to] Published successfully — ID: ${data.id}, URL: ${data.url}`);
+  return { id: String(data.id), url: data.url };
+}
+
+// ---------------------------------------------------------------------------
+// Hashnode publisher
+// ---------------------------------------------------------------------------
+
+async function publishToHashnode(article) {
+  const { title, description, tags, canonical_url, markdown } = article;
+
+  const tagObjects = (Array.isArray(tags) ? tags : []).map(t => ({
+    name: t,
+    slug: t.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+  }));
+
+  const mutation = `
+    mutation PublishPost($input: PublishPostInput!) {
+      publishPost(input: $input) {
+        post {
+          id
+          url
+        }
+      }
+    }
+  `;
+
+  const variables = {
+    input: {
+      title,
+      contentMarkdown: markdown,
+      publicationId: HASHNODE_PUBLICATION_ID,
+      tags: tagObjects,
+      originalArticleURL: canonical_url || undefined,
+      metaTags: description
+        ? { description }
+        : undefined,
+    },
+  };
+
+  console.log(`[Hashnode] Publishing: "${title}"`);
+
+  const response = await fetch('https://gql.hashnode.com/', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: HASHNODE_ACCESS_TOKEN,
+    },
+    body: JSON.stringify({ query: mutation, variables }),
+  });
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    throw new Error(`Hashnode API HTTP error ${response.status}: ${JSON.stringify(data)}`);
+  }
+
+  if (data.errors && data.errors.length > 0) {
+    const errMessages = data.errors.map(e => e.message).join('; ');
+    throw new Error(`Hashnode GraphQL errors: ${errMessages}`);
+  }
+
+  const post = data?.data?.publishPost?.post;
+  if (!post?.id) {
+    throw new Error(`Hashnode API returned unexpected response: ${JSON.stringify(data)}`);
+  }
+
+  console.log(`[Hashnode] Published successfully — ID: ${post.id}, URL: ${post.url}`);
+  return { id: post.id, url: post.url };
+}
+
+// ---------------------------------------------------------------------------
+// Publish log
+// ---------------------------------------------------------------------------
+
+async function loadPublishLog() {
+  try {
+    const raw = await readFile(PUBLISH_LOG, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return { articles: {} };
+  }
+}
+
+async function savePublishLog(log) {
+  await writeFile(PUBLISH_LOG, JSON.stringify(log, null, 2) + '\n', 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // Validate required secrets
+  const missing = [];
+  if (!DEVTO_API_KEY) missing.push('DEVTO_API_KEY');
+  if (!HASHNODE_ACCESS_TOKEN) missing.push('HASHNODE_ACCESS_TOKEN');
+  if (!HASHNODE_PUBLICATION_ID) missing.push('HASHNODE_PUBLICATION_ID');
+
+  if (missing.length > 0) {
+    console.error(`ERROR: Missing required environment variables: ${missing.join(', ')}`);
+    console.error('Set these as repository secrets in GitHub Actions.');
+    process.exit(1);
+  }
+
+  // Load article files
+  const files = (await readdir(ARTICLES_DIR)).filter(f => f.endsWith('.md'));
+
+  if (files.length === 0) {
+    console.log('No markdown files found in docs/articles/ — nothing to publish.');
+    return;
+  }
+
+  const log = await loadPublishLog();
+  let anyPublished = false;
+  let anyFailed = false;
+
+  for (const filename of files) {
+    const filepath = join(ARTICLES_DIR, filename);
+    const raw = await readFile(filepath, 'utf8');
+    const { frontmatter, body } = parseFrontmatter(raw);
+
+    if (frontmatter.published === true) {
+      console.log(`[skip] ${filename} — already published`);
+      continue;
+    }
+
+    const { title, description, tags, canonical_url } = frontmatter;
+
+    if (!title) {
+      console.warn(`[warn] ${filename} — missing title in frontmatter, skipping`);
+      continue;
+    }
+
+    // Strip HTML comments (demo gif placeholders etc.) from body for publishing.
+    // Loop until stable to avoid incomplete sanitization when nested fragments re-form.
+    let cleanBody = body;
+    let prev;
+    do {
+      prev = cleanBody;
+      cleanBody = cleanBody.replace(/<!--[\s\S]*?-->/g, '');
+    } while (cleanBody !== prev);
+    cleanBody = cleanBody.trim();
+
+    const article = { title, description, tags, canonical_url, markdown: cleanBody };
+    const slug = filename.replace(/\.md$/, '');
+    const logEntry = log.articles[slug] || {};
+
+    console.log(`\n=== Publishing: ${filename} ===`);
+
+    // dev.to
+    let devtoResult = null;
+    if (logEntry.devto?.id) {
+      console.log(`[dev.to] Already logged as published (ID: ${logEntry.devto.id}) — skipping`);
+      devtoResult = logEntry.devto;
+    } else {
+      try {
+        devtoResult = await publishToDevTo(article);
+        logEntry.devto = { ...devtoResult, publishedAt: new Date().toISOString() };
+        log.articles[slug] = logEntry;
+        await savePublishLog(log);
+      } catch (err) {
+        console.error(`[dev.to] FAILED for ${filename}: ${err.message}`);
+        anyFailed = true;
+      }
+    }
+
+    // Hashnode
+    let hashnodeResult = null;
+    if (logEntry.hashnode?.id) {
+      console.log(`[Hashnode] Already logged as published (ID: ${logEntry.hashnode.id}) — skipping`);
+      hashnodeResult = logEntry.hashnode;
+    } else {
+      try {
+        hashnodeResult = await publishToHashnode(article);
+        logEntry.hashnode = { ...hashnodeResult, publishedAt: new Date().toISOString() };
+        log.articles[slug] = logEntry;
+        await savePublishLog(log);
+      } catch (err) {
+        console.error(`[Hashnode] FAILED for ${filename}: ${err.message}`);
+        anyFailed = true;
+      }
+    }
+
+    // Only mark as published in frontmatter if both platforms succeeded
+    if (devtoResult && hashnodeResult) {
+      const updated = { ...frontmatter, published: true };
+      const newContent = serializeFrontmatter(updated, body);
+      await writeFile(filepath, newContent, 'utf8');
+      console.log(`[ok] ${filename} — frontmatter updated to published: true`);
+      anyPublished = true;
+    } else {
+      console.warn(`[warn] ${filename} — not fully published on both platforms; frontmatter NOT updated`);
+    }
+  }
+
+  await savePublishLog(log);
+
+  if (anyFailed) {
+    console.error('\nOne or more articles failed to publish. See errors above.');
+    process.exit(1);
+  }
+
+  if (!anyPublished) {
+    console.log('\nNo new articles to publish — all up to date.');
+  } else {
+    console.log('\nDone. All new articles published successfully.');
+  }
+}
+
+main().catch(err => {
+  console.error('Unexpected error:', err);
+  process.exit(1);
+});