dotdog 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.3.1
+
+- Fix npm packaging: homepage, bugs, engines, repository fields
+- Trim keywords to 8 specific terms
+- Ship correct README, LICENSE, and CHANGELOG in package
+- CLI help text uses colons, no em dashes
+
+## 0.3.0
+
+- `dotdog analyze` — deep project analysis: score, gaps, entity audit
+- `dotdog generate` — generate missing spec files from SPEC.dog
+- `dotdog simulate` — run simulation scenarios
+- `.dag` v1.2: provable token savings, typed nodes and edges
+- VS Code extension: syntax highlighting for .dog files
+- GitHub Pages and llms.txt for AI agent discoverability
+- `dotdog serve` MCP server: getEntity, traverse, search, schema, summary
+- Path traversal guard, traverse depth cap, serve hardening
+
+## 0.2.0
+
+- `dotdog compile` — compile .dog files to .dag graph
+- `dotdog visualize` — Mermaid graph output with --save flag
+- MCP server: expose .dag graph to AI agents over stdio
+- `dotdog staleness` — detect drift between spec and reality
+- `dotdog init` — scaffold new spec genome projects
+- `dotdog list` — list all projects and .dog file counts
+
+## 0.1.0
+
+- `.dog` file format v1.0
+- `.dag` file format v1.0
+- `dotdog validate` — validate spec completeness
+- `dotdog parse` — parse .dog files

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 specdog
+
+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/README.md

@@ -1,76 +1,130 @@
-# spec-platform
+# dotdog
 
-Monorepo for the Spec Platform — a knowledge graph system where specs ARE the database and LLMs ARE the query engine.
+[![npm version](https://img.shields.io/npm/v/dotdog)](https://www.npmjs.com/package/dotdog)
+[![npm downloads](https://img.shields.io/npm/dm/dotdog)](https://www.npmjs.com/package/dotdog)
+[![License: MIT](https://img.shields.io/npm/l/dotdog)](https://github.com/specdog/dotdog/blob/main/LICENSE)
+[![CI](https://github.com/specdog/dotdog/actions/workflows/test.yml/badge.svg)](https://github.com/specdog/dotdog/actions)
 
-## The Flywheel
+> **Feed the dog. Ship with specs.** Write .dog specs. Dog checks them. AI agents fetch them.
 
-```
-spec → validate → app → data → better spec → better app → ...
+## Install
+
+```bash
+npm install -g dotdog
 ```
 
-The spec describes the platform. The platform validates the spec. The validation report improves the spec. Each cycle adds granularity.
+Requires Node.js >= 20.
 
-## Structure
+## Quick Start
 
+```bash
+dotdog init my-project     # scaffold a spec genome
+dotdog validate            # score completeness (0-100%)
+dotdog analyze             # deep analysis : gaps, suggestions, entity audit
 ```
-spec-platform/
-├── packages/
-│   ├── spec-engine/     # Core types and ontology (shared by everything)
-│   ├── spec-mcp/        # MCP Server — AI agents query specs via stdio
-│   └── spec-cli/        # CLI — spec validate, init, simulate, list
-├── projects/            # Spec genomes (dogfooding)
-│   └── spec-platform/
-│       └── specs/
-│           ├── SPEC.dog          # Product spec — screens, flows, stories
-│           ├── constitution.dog  # Immutable rules
-│           └── data-model.dog    # Graph ontology — nodes, edges, tasks, predictions, vectors
-├── templates/           # Spec genome templates for new projects
-└── package.json         # Bun workspace root
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `dotdog validate [dir]` | Score spec completeness. Checks file existence, entity descriptions, section counts. |
+| `dotdog analyze [dir]` | Deep analysis. Detects domain, stack, gaps with severity, entity quality audit. |
+| `dotdog parse <file>` | Parse a `.dog` file into sections. |
+| `dotdog compile [dir]` | Compile `.dog` files into a `.dag` graph (JSON). |
+| `dotdog visualize [dir]` | Output Mermaid graph from `.dag`. `--save` writes `.md` for GitHub rendering. |
+| `dotdog serve [dir]` | Start MCP server over stdio. AI agents query specs without hallucination. |
+| `dotdog staleness [dir]` | Detect drift between spec and reality. Compares plan.dog tasks against code. |
+| `dotdog generate [dir]` | Generate missing spec files from SPEC.dog (data-model, COPY, INDEX). |
+| `dotdog simulate <scenario>` | Run a simulation scenario. Reads SPEC.dog scenarios, checks pre/postconditions. |
+| `dotdog init <project>` | Scaffold a new spec genome project with templates. |
+| `dotdog list` | List all projects and their `.dog` file counts. |
+
+## File Formats
+
+### `.dog` : Human-Written Spec Genome
+
+Markdown prose + YAML structured blocks. Free and open source. Define entities, relationships, events, predictions, and copy in a single format that both humans and parsers understand.
+
+```markdown
+### Entity: User
+
+A person who uses the app.
+
+` ``yaml
+entity: User
+type: entity
+properties:
+  id:
+    type: string
+    required: true
+  email:
+    type: string
+    required: true
+states: [active, suspended]
+lifecycle: active → suspended
+` ``
 ```
 
-## Quick Start
+### `.dag` : Machine-Compiled Graph
 
-```bash
-bun install
-cd projects/spec-platform/specs
+JSON graph compiled from `.dog` files. Nodes, edges, properties, and states in a deterministic structure. 85% token savings vs raw `.dog` files for AI agents.
 
-# Validate our own spec (dogfood)
-bun ../../../packages/spec-cli/src/index.ts validate ../..
+## MCP Server : AI Agent Integration
 
-# List projects
-bun ../../../packages/spec-cli/src/index.ts list
-```
+`dotdog serve` exposes specs to any MCP-compatible AI agent over stdio. Six tools:
 
-## $0 Stack
+| Tool | Description |
+|------|-------------|
+| `getEntity` | Exact entity with properties, states, lifecycle, and connected edges |
+| `traverse` | BFS subgraph from any starting node to any depth |
+| `search` | Find entities by name or type |
+| `schema` | Property definitions only : zero prose, agent-optimized |
+| `summary` | Node count, edge count, file count, compile time |
+| `listProjects` | Array of project names |
 
-| Component | Technology | Cost |
-|-----------|-----------|------|
-| Runtime | Bun | $0 |
-| Database | bun:sqlite (embedded) | $0 |
-| Types | TypeScript (strict) | $0 |
-| CLI | Commander.js + chalk | $0 |
-| MCP Server | @modelcontextprotocol/sdk (stdio) | $0 |
-| Embeddings | all-MiniLM-L6-v2 (local) | $0 |
-| Hosting | None needed (local-first) | $0 |
+Agent workflow: `listProjects` → `getEntity` → `traverse` graph.
 
-## The Spec Graph
+## Dogfood
 
-The spec is not a document. It's a knowledge graph.
+dotdog validates its own specs. Every PR:
+
+```
+dotdog validate → find gaps → fix spec → PR → merge → tag → CI publish
+```
 
-- **Nodes**: entities, tasks, predictions, screens, constraints, user stories
-- **Edges**: contains, depends_on, implements, references, calls, precedes
-- **Vectors**: every section embedded for semantic search, contradiction detection, staleness checks
-- **Predictions**: forecasts with triggers, timeframes, confidence, and actual outcome tracking
+Eat your own dogfood. The tool is the project.
 
-LLMs traverse the graph at query time. They don't read prose and guess — they get exact typed values.
+## VS Code Extension
 
-## Score
+Syntax highlighting for `.dog` files. Install:
 
+```bash
+cp -r extensions/vscode ~/.vscode/extensions/dotdog
 ```
-spec validate → 43% complete
 
-  ✓ SPEC.dog
-  ✓ constitution.dog
-  ✓ data-model.dog
-  ⚠ COPY.dog, DESIGN-SYSTEM.dog, plan.dog, INDEX.dog
+## Format Specifications
+
+- [`.dog` format spec](spec/format-spec.dog) : language definition, EBNF grammar, validation rules
+- [`.dag` format spec](spec/format-spec-dag.dog) : graph definition, MCP API, token efficiency
+
+## Links
+
+- **GitHub:** [specdog/dotdog](https://github.com/specdog/dotdog)
+- **npm:** [dotdog](https://www.npmjs.com/package/dotdog)
+- **Docs:** [GitHub Pages](https://specdog.github.io/dotdog)
+- **llms.txt:** [llms.txt](llms.txt) : structured for AI agent discovery
+- **AGENTS.md:** [AGENTS.md](AGENTS.md) : instructions for AI coding agents
+
+## Spec-Driven Development
+
+dotdog is built for SDD. Write your spec first. Validate it. Compile it. Let AI agents query it. The spec is the source of truth.
+
+```
+spec → validate → compile → serve → AI agent queries
 ```
+
+No more specs that rot in a wiki. No more agents guessing from prose. One source. Zero ambiguity.
+
+## License
+
+MIT

package/dist/cli.js

@@ -2535,7 +2535,7 @@ var source_default = chalk;
 
 // src/cli.ts
 import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, mkdirSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
+import { join as join2, resolve as resolve2 } from "path";
 import { homedir as homedir2 } from "os";
 import { createHash } from "crypto";
 
@@ -2897,13 +2897,21 @@ function parseInlineObject(value) {
 }
 // src/serve.ts
 import { existsSync, readdirSync, readFileSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
 import { homedir } from "os";
 import * as readline from "readline";
 function resolvePath(p) {
   if (p.startsWith("~"))
     p = join(homedir(), p.slice(1));
-  return p.startsWith("/") ? p : join(process.cwd(), p);
+  const resolved = p.startsWith("/") ? p : join(process.cwd(), p);
+  if (!p.startsWith("/") && !p.startsWith("~")) {
+    const rel = resolve(process.cwd(), p);
+    if (!rel.startsWith(process.cwd() + "/") && rel !== process.cwd()) {
+      throw new Error(`Path traversal blocked: ${p}`);
+    }
+    return rel;
+  }
+  return resolved;
 }
 function serve(dir = ".") {
   const root = resolvePath(dir);
@@ -2978,7 +2986,7 @@ function serve(dir = ".") {
         const dag = dagCache.get(args.project || [...dagCache.keys()][0] || "");
         if (!dag)
           return { jsonrpc: "2.0", id, error: { code: 404, message: "Project not found" } };
-        const depth = args.depth || 1;
+        const depth = Math.min(Math.max(1, args.depth || 1), 20);
         const visited = new Set;
         const subgraph = { nodes: [], edges: [] };
         const queue = [{ id: args.from, depth: 0 }];
@@ -3060,7 +3068,15 @@ function serve(dir = ".") {
 function resolvePath2(p) {
   if (p.startsWith("~"))
     p = join2(homedir2(), p.slice(1));
-  return p.startsWith("/") ? p : join2(process.cwd(), p);
+  const resolved = p.startsWith("/") ? p : join2(process.cwd(), p);
+  if (!p.startsWith("/") && !p.startsWith("~")) {
+    const rel = resolve2(process.cwd(), p);
+    if (!rel.startsWith(process.cwd() + "/") && rel !== process.cwd()) {
+      throw new Error(`Path traversal blocked: ${p}`);
+    }
+    return rel;
+  }
+  return resolved;
 }
 function parseSections2(markdown) {
   const lines = markdown.split(`
@@ -3095,9 +3111,10 @@ function parseSections2(markdown) {
 }
 var program2 = new Command;
 var pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf-8"));
-program2.name("spec").alias("dotdog").description("The spec dog — validate, analyze, generate, simulate .dog files").version(pkg.version);
+program2.name("spec").alias("dotdog").description("CLI for structured software specs : validate .dog, compile .dag, query via MCP").version(pkg.version);
 program2.command("validate [dir]").action((d = ".") => {
-  const dirs = [join2(d, "projects"), join2(d, "specs")];
+  const dir = resolvePath2(d);
+  const dirs = [join2(dir, "projects"), join2(dir, "specs")];
   let found = false;
   for (const dd of dirs) {
     if (!existsSync2(dd))
@@ -3110,7 +3127,7 @@ program2.command("validate [dir]").action((d = ".") => {
       const missing = ["SPEC.dog", "constitution.dog", "data-model.dog"].filter((f) => !files.includes(f));
       const optional = ["COPY.dog", "plan.dog", "DESIGN-SYSTEM.dog", "INDEX.dog"].filter((f) => !files.includes(f));
       console.log(source_default.bold(`
-  ${p} — ${files.length} .dog files, ${100 - Math.round((missing.length * 3 + optional.length) / 20 * 100)}% complete`));
+  ${p} : ${files.length} .dog files, ${100 - Math.round((missing.length * 3 + optional.length) / 20 * 100)}% complete`));
       for (const f of files)
         console.log(source_default.gray(`    ${f}`));
       if (missing.length)
@@ -3177,7 +3194,7 @@ ${d}/`));
     for (const p of projects) {
       const sp = join2(dd, p, "specs");
       const n = existsSync2(sp) ? readdirSync2(sp).filter((f) => f.endsWith(".dog")).length : 0;
-      console.log(`  ${source_default.cyan(p)} — ${n} .dog files`);
+      console.log(`  ${source_default.cyan(p)} : ${n} .dog files`);
     }
   }
 });
@@ -3286,7 +3303,7 @@ program2.command("visualize [dir]").option("-s, --save").action((d = ".", opts)
       out += "```\n";
       if (opts.save) {
         const outFile = join2(dd, p, "..", `${p}.md`);
-        writeFileSync(outFile, `# ${p} — Spec Graph
+        writeFileSync(outFile, `# ${p} : Spec Graph
 
 ${out}`);
         console.log(source_default.green(`  ✓ ${outFile}`));
@@ -3295,8 +3312,8 @@ ${out}`);
     }
   }
 });
-program2.command("serve [dir]").description("MCP server — expose .dag graph to AI agents over stdio").action((d = ".") => serve(d));
-program2.command("analyze [dir]").description("Analyze a spec project — score, gaps, suggestions").option("-p, --project <name>").action((d = ".", opts) => {
+program2.command("serve [dir]").description("MCP server : expose .dag graph to AI agents over stdio").action((d = ".") => serve(resolvePath2(d)));
+program2.command("analyze [dir]").description("Analyze a spec project : score, gaps, suggestions").option("-p, --project <name>").action((d = ".", opts) => {
   const dir = resolvePath2(d);
   const dirs = [join2(dir, "projects"), join2(dir, "specs"), dir];
   console.log(source_default.bold(`
@@ -3344,7 +3361,7 @@ Spec Analysis
       console.log(`  ${files.length} files | ${score}% complete`);
       for (const a of analyses) {
         const detail = a.entities > 0 ? ` (${a.entities} entities, ${a.rels} rels)` : "";
-        console.log(source_default.gray(`    ${a.file} — ${a.sections} sections, ${(a.size / 1024).toFixed(1)}KB${detail}`));
+        console.log(source_default.gray(`    ${a.file} : ${a.sections} sections, ${(a.size / 1024).toFixed(1)}KB${detail}`));
       }
       const gaps = [];
       for (const f of missingReq)
@@ -3495,7 +3512,7 @@ program2.command("simulate <scenario>").description("Run a simulation scenario (
   console.log(source_default.bold(`
 Simulation: ${scenario} (project: ${opts.project})
 `));
-  console.log(source_default.gray("Simulation engine — reads SPEC.dog scenarios, walks through steps, checks pre/postconditions."));
+  console.log(source_default.gray("Simulation engine : reads SPEC.dog scenarios, walks through steps, checks pre/postconditions."));
   console.log(source_default.gray("Full engine coming in a future release."));
 });
 program2.command("staleness [dir]").action((d = ".") => {
@@ -3556,6 +3573,13 @@ program2.command("staleness [dir]").action((d = ".") => {
     }
   }
 });
+program2.command("woof").action(() => {
+  console.log("  / \\__");
+  console.log(" (    @\\___");
+  console.log("  /       O");
+  console.log(" /   (_____/");
+  console.log("/_____/   U");
+});
 program2.parse();
 export {
   parseToJSON,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dotdog",
-  "version": "0.3.0",
-  "description": "The spec dog — structured, AI-queryable software specifications. Write .dog specs, compile to .dag graphs, query via MCP. Built for humans and AI agents.",
+  "version": "0.3.1",
+  "description": "CLI tool for structured software specifications. Validate .dog files, compile .dag graphs, query via MCP.",
   "type": "module",
   "main": "dist/cli.js",
   "bin": {
@@ -15,26 +15,28 @@
     "LICENSE"
   ],
   "keywords": [
-    "spec",
     "specification",
-    "ai",
-    "agent",
-    "mcp",
-    "documentation",
     "cli",
-    "spec-driven-development",
+    "mcp",
     "graph",
-    "markdown",
-    "yaml",
-    "dotdog",
     "dag",
-    "dog"
+    "yaml",
+    "markdown",
+    "spec-driven-development"
   ],
   "license": "MIT",
   "author": "specdog",
+  "homepage": "https://github.com/specdog/dotdog#readme",
+  "bugs": {
+    "url": "https://github.com/specdog/dotdog/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/specdog/dotdog.git"
+    "url": "https://github.com/specdog/dotdog.git",
+    "directory": "packages/dotdog"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "dependencies": {
     "commander": "^15.0.0",