@dforge-core/dforge-mcp 0.1.11 → 0.2.0

package/docs/creating-modules.md

@@ -42,20 +42,28 @@ Sidebar also gives you right-click commands: **Pack Module**, **Install Module t
 
 ## Path 3 — AI co-pilot, wizard-driven
 
-Claude Code (or Cursor / Zed) with `dforge-mcp` connected. You describe what you want; the AI walks you through six phases via MCP tool calls, pausing at each gate for your approval.
+Claude Code (or Cursor / Zed) with `dforge-mcp` connected. You describe what you want; the AI walks you through seven phases (0-6) via MCP tool calls, pausing at each gate for your approval. Guidance ships as four skills — a router plus one per lifecycle stage — so only the active stage is loaded.
 
 Setup once:
 
 ```bash
 claude mcp add dforge --scope user -- npx -y @dforge-core/dforge-mcp
-# Resolve actual latest from npm, then pin jsdelivr URL to it.
-# (jsdelivr's @latest endpoint caches 6-12h; pinning the version skips that.)
-VERSION=$(npm view @dforge-core/dforge-mcp version)
-mkdir -p ~/.claude/skills/dforge-mcp-author
-curl -fsSL "https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@${VERSION}/skills/dforge-mcp-author/SKILL.md" \
-  -o ~/.claude/skills/dforge-mcp-author/SKILL.md
+
+# Install the four authoring skills into ~/.claude/skills/
+npx -y -p @dforge-core/dforge-mcp dforge-install-skills
 ```
 
+That works as-is on Windows (cmd.exe / PowerShell), macOS and Linux — it's a
+Node script, not bash. From a clone, `npm run install-skills` installs the local
+copy instead. See the README's "Windows notes" for the WSL caveat.
+
+| Skill | Stage |
+|---|---|
+| `dforge-mcp-author` | Router — finds the current phase and hands off |
+| `dforge-module-design` | Phase 0 — identity, requirements, design, validation |
+| `dforge-module-build` | Phases 1-5 — entities, behavior, views, security |
+| `dforge-module-ship` | Phase 6 — validate, pack, install |
+
 Restart Claude Code, approve the MCP server on first prompt, then in a new conversation:
 
 ```
@@ -66,7 +74,7 @@ The wizard runs:
 
 ### Phase 0 — Identity, requirements, design, validation (required)
 
-A documented chain the `dforge-mcp-author` skill enforces — the AI authors each artifact directly (drafts it, you approve, your client writes the file):
+A documented chain the `dforge-module-design` skill enforces — the AI authors each artifact directly (drafts it, you approve, your client writes the file):
 
 - **0a Identity** — write `CLAUDE.md` (identity + MCP-first rules + a live status tracker).
 - **0b Requirements** — intake questions (purpose / users / dependencies / language scope), then write `docs/REQUIREMENTS.md`. **You review it before moving on.**
@@ -148,6 +156,9 @@ VS Code with the [dForge extension](https://github.com/dforge-core/dforge-editor
 
 ## Going further
 
-- [SKILL.md](../skills/dforge-mcp-author/SKILL.md) — the full wizard spec the AI follows, including the deterministic backtrack protocol, multi-trigger priority rule, tool-failure protocol, and resume-from-partial-state support
-- [README.md](../README.md) — full tool reference (18 tools, 13 resources) + maintainer docs
+- [dforge-mcp-author](../skills/dforge-mcp-author/SKILL.md) — the router: session start, tool inventory, hard rules, tool-failure protocol, resource index
+- [dforge-module-design](../skills/dforge-module-design/SKILL.md) — Phase 0, including the intake guardrails and gap scans
+- [dforge-module-build](../skills/dforge-module-build/SKILL.md) — Phases 1-5, the loading-policy table, core-rules cheat sheet, and the deterministic backtrack protocol
+- [dforge-module-ship](../skills/dforge-module-ship/SKILL.md) — Phase 6 and the install-fix loop
+- [README.md](../README.md) — full tool reference (34 tools) + maintainer docs
 - [iash44/dForge-core](https://github.com/iash44/dForge-core) — the platform itself: source of truth for the schemas + DSL conventions

package/package.json

@@ -1,45 +1,48 @@
 {
-	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.11",
-	"description": "MCP server for dForge module authoring. Exposes scaffold/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
-	"license": "MIT",
-	"homepage": "https://github.com/iash44/dForge-core",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
-	},
-	"bin": {
-		"dforge-mcp": "dist/server.js"
-	},
-	"files": [
-		"dist/",
-		"docs/",
-		"resources/",
-		"skills/",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"main": "dist/server.js",
-	"engines": {
-		"node": ">=18"
-	},
-	"scripts": {
-		"build": "tsup",
-		"sync-schemas": "node scripts/vendor-schemas.cjs",
-		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
-		"typecheck": "tsc --noEmit",
-		"test": "vitest run"
-	},
-	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.7",
-		"@dforge-core/metadata": "^0.0.9",
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"zod": "^4.4.3"
-	},
-	"devDependencies": {
-		"@types/node": "^22.20.1",
-		"tsup": "^8.5.1",
-		"typescript": "^6.0.3",
-		"vitest": "^3.2.7"
-	}
+  "name": "@dforge-core/dforge-mcp",
+  "version": "0.2.0",
+  "description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
+  "license": "MIT",
+  "homepage": "https://github.com/iash44/dForge-core",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dforge-core/dforge-mcp.git"
+  },
+  "bin": {
+    "dforge-mcp": "dist/server.js",
+    "dforge-install-skills": "scripts/install-skills.mjs"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "resources/",
+    "skills/",
+    "scripts/install-skills.mjs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "main": "dist/server.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "sync-schemas": "node scripts/vendor-schemas.cjs",
+    "prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "install-skills": "node scripts/install-skills.mjs"
+  },
+  "dependencies": {
+    "@dforge-core/dforge-cli": "^0.2.7",
+    "@dforge-core/metadata": "^0.0.10",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.7"
+  }
 }

package/resources/docs/dsl-reference.md

@@ -417,6 +417,32 @@ var result = callService('studio.validate', { module_cd: [module_cd] })
 if (!result.isValid) { error('Validation failed: ' + result.errors[0]) }
 ```
 
+### Document extraction (OCR)
+
+Full guide + intake patterns: `dforge://reference/document-extraction`.
+
+#### `ocrExtract(fileField, endpointBaseUrl, schemaOrHints?, opts?) → string | object`
+Send a file to the OCR service and get structured fields back. Three forms:
+
+- **v1 (raw):** `ocrExtract([doc_file], getSetting('ocr_endpoint_url'))` → JSON **string** (you `JSON.parse`). Optional third arg = hints (array | string | object).
+- **v2 inline schema:** `ocrExtract([doc_file], url, schema, { mode: 'extract' })` → **parsed** `{ fields, confidence?, unmatched, raw_text, meta }`.
+- **v2 profile:** `ocrExtract([doc_file], url, null, { profile: 'module_cd.profile_cd' })` → same parsed shape, schema from `logic/extraction_profiles.json`.
+
+v2 is selected **only** by `opts.mode` (`'extract' | 'summary' | 'raw'`) or `opts.profile` — a bare schema object without `opts.mode` stays on the v1 (raw string) contract. `opts.profile` implies `mode: 'extract'` and is mutually exclusive with an inline `schema`.
+
+```dsl
+var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), null, { profile: 'proc.bill_of_lading' })
+insert('bill_of_lading', { bl_no: r.fields.bl_no, issue_date: r.fields.issue_date })
+```
+
+#### `detectDocument(rawText) → object | null`
+Score a document's text against every reachable extraction profile's `detect` rules and return the best match at/above its threshold: `{ profile, docType, score }` (profile module-qualified, ready for `ocrExtract(..., { profile })`) — or `null`. Advisory: malformed rules are skipped, let the human confirm.
+
+```dsl
+var det = detectDocument(data.raw_text)     // { profile: 'proc.bill_of_lading', docType: 'bill_of_lading', score } | null
+if (det != null) { var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), null, { profile: det.profile }) }
+```
+
 ### Utility
 
 #### `entityLink(entityCd, record, description?) → link value`

package/scripts/install-skills.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Install the dForge authoring skills into the Claude skills directory.
+//
+// The skills ship inside the npm tarball, but Claude Code only looks in
+// <config>/skills — not node_modules — so they have to be copied out. There are
+// four (a router plus three stage skills), and the router's directory also
+// carries the shared references/ + examples/ the MCP server serves as dforge://
+// resources, so hand-copying is error-prone.
+//
+// Written in Node rather than bash so it behaves identically on Windows
+// (cmd.exe, PowerShell), macOS, Linux, Git Bash and WSL. The bash version this
+// replaced could not run in cmd/PowerShell at all, and under WSL it resolved
+// $HOME to the LINUX home — silently installing to /home/you/.claude while
+// Claude Code on Windows read C:\Users\you\.claude.
+//
+// Usage:
+//   node scripts/install-skills.mjs              # from a local checkout
+//   node scripts/install-skills.mjs --from-npm   # download the published version
+//   DEST=/some/where node scripts/install-skills.mjs
+//
+//   npm run install-skills
+//   npm run install-skills -- --from-npm
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILLS = [
+	["dforge-mcp-author", "router — start here; also holds the shared\n                        references/ and examples/ the MCP server serves"],
+	["dforge-module-design", "Phase 0  — identity, intake, design, validation"],
+	["dforge-module-build", "Phases 1-5 — entities, behavior, views, security"],
+	["dforge-module-ship", "Phase 6  — validate, pack, install-fix loop"],
+];
+
+const PKG = "@dforge-core/dforge-mcp";
+const fromNpm = process.argv.includes("--from-npm");
+
+// Piping into `head`/`less` closes our stdout mid-write; without this Node
+// turns that into an unhandled EPIPE and dumps a stack trace over what is
+// otherwise a successful install.
+for (const stream of [process.stdout, process.stderr]) {
+	stream.on("error", (e) => {
+		if (e.code === "EPIPE") process.exit(0);
+		throw e;
+	});
+}
+
+/**
+ * Where Claude Code looks for skills. `CLAUDE_CONFIG_DIR` wins when set;
+ * otherwise `<home>/.claude/skills`. os.homedir() is the point of this being a
+ * Node script — on Windows it's %USERPROFILE% regardless of which shell (or
+ * shell emulator) invoked us.
+ */
+function defaultDest() {
+	if (process.env.DEST) return process.env.DEST;
+	const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+	return path.join(configDir, "skills");
+}
+
+/** npm is a .cmd shim on Windows, which spawn can only launch through a shell. */
+const NPM = process.platform === "win32" ? "npm.cmd" : "npm";
+
+function npm(args, opts = {}) {
+	const r = spawnSync(NPM, args, {
+		encoding: "utf8",
+		shell: process.platform === "win32",
+		...opts,
+	});
+	if (r.error) {
+		throw new Error(`Failed to run \`npm ${args.join(" ")}\`: ${r.error.message}. Is npm on your PATH?`);
+	}
+	if (r.status !== 0) {
+		throw new Error(`\`npm ${args.join(" ")}\` failed (exit ${r.status}):\n${r.stderr || r.stdout}`);
+	}
+	return (r.stdout || "").trim();
+}
+
+/**
+ * Download + unpack the published tarball into a temp dir, returning its
+ * skills/ path. Uses `npm pack` (which fetches only this package, not its
+ * ~35 MB native CLI dependency) plus `tar`, which ships with Windows 10 1803+,
+ * macOS and every Linux.
+ */
+function fetchFromNpm(tmp) {
+	// Resolve the real latest version rather than relying on a CDN alias that
+	// caches for hours after a publish and would serve stale skills.
+	const version = npm(["view", PKG, "version"]);
+	process.stdout.write(`Fetching ${PKG}@${version} …\n`);
+	npm(["pack", `${PKG}@${version}`, "--pack-destination", tmp], { cwd: tmp });
+
+	const tarball = fs.readdirSync(tmp).find((f) => f.endsWith(".tgz"));
+	if (!tarball) throw new Error(`npm pack produced no .tgz in ${tmp}`);
+
+	const r = spawnSync("tar", ["-xzf", path.join(tmp, tarball), "-C", tmp], { encoding: "utf8" });
+	if (r.error || r.status !== 0) {
+		throw new Error(
+			`Could not extract ${tarball}: ${r.error?.message ?? r.stderr}\n` +
+				"`tar` is required (built into Windows 10 1803+, macOS and Linux). " +
+				"Alternatively clone the repo and run this script without --from-npm.",
+		);
+	}
+	return path.join(tmp, "package", "skills");
+}
+
+function main() {
+	const dest = defaultDest();
+	let tmp;
+	let src;
+
+	try {
+		if (fromNpm) {
+			tmp = fs.mkdtempSync(path.join(os.tmpdir(), "dforge-skills-"));
+			src = fetchFromNpm(tmp);
+		} else {
+			// Relative to this file, so it works from any cwd.
+			const here = path.dirname(fileURLToPath(import.meta.url));
+			src = path.join(here, "..", "skills");
+		}
+
+		if (!fs.existsSync(src)) {
+			throw new Error(
+				`No skills directory at ${src}.` +
+					(fromNpm ? "" : " Run with --from-npm to install from the published package instead."),
+			);
+		}
+
+		fs.mkdirSync(dest, { recursive: true });
+		let installed = 0;
+		for (const [skill] of SKILLS) {
+			const from = path.join(src, skill);
+			if (!fs.existsSync(from)) {
+				process.stderr.write(`  ! skipping ${skill} (not found in ${src})\n`);
+				continue;
+			}
+			// Replace wholesale: a stale reference file left behind is worse than a
+			// missing one, because the agent will happily author against it.
+			fs.rmSync(path.join(dest, skill), { recursive: true, force: true });
+			fs.cpSync(from, path.join(dest, skill), { recursive: true });
+			process.stdout.write(`  \u2713 ${skill}\n`);
+			installed++;
+		}
+
+		if (installed === 0) throw new Error(`No skills were installed from ${src}.`);
+
+		process.stdout.write(
+			`\nInstalled ${installed} skill${installed === 1 ? "" : "s"} to ${dest}\n\n`,
+		);
+		for (const [skill, blurb] of SKILLS) {
+			process.stdout.write(`  ${skill.padEnd(21)} ${blurb}\n`);
+		}
+		process.stdout.write(
+			"\nRe-run after every dforge-mcp upgrade. The skill version is not checked at\n" +
+				"runtime, so stale skills against new tools will misroute calls.\n",
+		);
+	} catch (e) {
+		process.stderr.write(`error: ${e.message}\n`);
+		process.exitCode = 1;
+	} finally {
+		if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+	}
+}
+
+main();