opentology 0.1.0

package/dist/templates/claude-md-context.d.ts

@@ -0,0 +1,4 @@
+export declare const MARKER_BEGIN = "<!-- OPENTOLOGY:CONTEXT:BEGIN -->";
+export declare const MARKER_END = "<!-- OPENTOLOGY:CONTEXT:END -->";
+export declare function generateContextSection(projectId: string, graphUri: string): string;
+export declare function updateClaudeMd(filePath: string, section: string): void;

package/dist/templates/claude-md-context.js

@@ -0,0 +1,104 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+export const MARKER_BEGIN = '<!-- OPENTOLOGY:CONTEXT:BEGIN -->';
+export const MARKER_END = '<!-- OPENTOLOGY:CONTEXT:END -->';
+export function generateContextSection(projectId, graphUri) {
+    const contextUri = `${graphUri}/context`;
+    const sessionsUri = `${graphUri}/sessions`;
+    return `${MARKER_BEGIN}
+## Context Management — OpenTology
+
+This project uses OpenTology as its project context graph.
+
+### Graph Structure
+
+| Graph | URI | Purpose |
+|-------|-----|---------|
+| context | \`${contextUri}\` | Decisions, issues, knowledge |
+| sessions | \`${sessionsUri}\` | Session work logs |
+
+### Ontology (\`otx:\` prefix)
+
+| Class | Description |
+|-------|-------------|
+| \`otx:Project\` | Project hub info |
+| \`otx:Decision\` | Architecture/tech decisions |
+| \`otx:Issue\` | Bugs and issues |
+| \`otx:Knowledge\` | Reusable knowledge |
+| \`otx:Session\` | Session logs |
+| \`otx:Pattern\` | Recurring patterns/conventions |
+
+| Property | Range | Description |
+|----------|-------|-------------|
+| \`otx:title\` | string | Title |
+| \`otx:date\` | date | Date (YYYY-MM-DD) |
+| \`otx:body\` | string | Body content |
+| \`otx:status\` | string | Status (open/resolved/active) |
+| \`otx:reason\` | string | Decision rationale |
+| \`otx:nextTodo\` | string | Next action item |
+| \`otx:relatedTo\` | resource | Related entity |
+
+### When to Record
+
+| Trigger | Type | Graph |
+|---------|------|-------|
+| Architecture/tech decision | \`otx:Decision\` | context |
+| Bug/issue resolved | \`otx:Issue\` | context |
+| Reusable knowledge | \`otx:Knowledge\` | context |
+| Session end | \`otx:Session\` | sessions |
+
+### Query Examples
+
+\`\`\`sparql
+# Recent sessions
+PREFIX otx: <https://opentology.dev/vocab#>
+SELECT ?title ?date ?nextTodo WHERE {
+  GRAPH <${sessionsUri}> {
+    ?s a otx:Session ; otx:title ?title ; otx:date ?date .
+    OPTIONAL { ?s otx:nextTodo ?nextTodo }
+  }
+} ORDER BY DESC(?date) LIMIT 5
+
+# Open issues
+PREFIX otx: <https://opentology.dev/vocab#>
+SELECT ?title ?date WHERE {
+  GRAPH <${contextUri}> {
+    ?s a otx:Issue ; otx:title ?title ; otx:date ?date ; otx:status "open" .
+  }
+} ORDER BY DESC(?date)
+\`\`\`
+
+### Session End Reminder
+
+At the end of each session, push a summary:
+
+\`\`\`turtle
+@prefix otx: <https://opentology.dev/vocab#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<urn:session:YYYY-MM-DD> a otx:Session ;
+    otx:title "Session summary here" ;
+    otx:date "YYYY-MM-DD"^^xsd:date ;
+    otx:body "What was done" ;
+    otx:nextTodo "What to do next" .
+\`\`\`
+${MARKER_END}`;
+}
+export function updateClaudeMd(filePath, section) {
+    if (!existsSync(filePath)) {
+        // Case 1: No file — create with just the section
+        writeFileSync(filePath, section + '\n', 'utf-8');
+        return;
+    }
+    const content = readFileSync(filePath, 'utf-8');
+    const beginIdx = content.indexOf(MARKER_BEGIN);
+    const endIdx = content.indexOf(MARKER_END);
+    if (beginIdx === -1 || endIdx === -1) {
+        // Case 2: File exists but no markers — append
+        writeFileSync(filePath, content.trimEnd() + '\n\n' + section + '\n', 'utf-8');
+        return;
+    }
+    // Case 3: File exists with markers — replace between markers
+    const before = content.substring(0, beginIdx);
+    const after = content.substring(endIdx + MARKER_END.length);
+    writeFileSync(filePath, before + section + after, 'utf-8');
+}

package/dist/templates/otx-ontology.d.ts

@@ -0,0 +1,2 @@
+export declare const OTX_BOOTSTRAP_TURTLE = "@prefix otx: <https://opentology.dev/vocab#> .\n@prefix owl: <http://www.w3.org/2002/07/owl#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n\notx:Project a owl:Class .\notx:Decision a owl:Class .\notx:Issue a owl:Class .\notx:Knowledge a owl:Class .\notx:Session a owl:Class .\notx:Pattern a owl:Class .\notx:Module a owl:Class .\n\notx:title a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:date a owl:DatatypeProperty ; rdfs:range xsd:date .\notx:body a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:status a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:reason a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:cause a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:solution a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:nextTodo a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:relatedTo a owl:ObjectProperty .\notx:project a owl:ObjectProperty .\notx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Module .\notx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .\n";
+export declare function buildAskQuery(contextGraphUri: string): string;

package/dist/templates/otx-ontology.js

@@ -0,0 +1,31 @@
+export const OTX_BOOTSTRAP_TURTLE = `\
+@prefix otx: <https://opentology.dev/vocab#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+otx:Project a owl:Class .
+otx:Decision a owl:Class .
+otx:Issue a owl:Class .
+otx:Knowledge a owl:Class .
+otx:Session a owl:Class .
+otx:Pattern a owl:Class .
+otx:Module a owl:Class .
+
+otx:title a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:date a owl:DatatypeProperty ; rdfs:range xsd:date .
+otx:body a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:status a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:reason a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:cause a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:solution a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:nextTodo a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:relatedTo a owl:ObjectProperty .
+otx:project a owl:ObjectProperty .
+otx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Module .
+otx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .
+`;
+export function buildAskQuery(contextGraphUri) {
+    return `ASK { GRAPH <${contextGraphUri}> { <https://opentology.dev/vocab#Decision> a <http://www.w3.org/2002/07/owl#Class> } }`;
+}

package/dist/templates/session-start-hook.d.ts

@@ -0,0 +1 @@
+export declare function generateHookScript(): string;

package/dist/templates/session-start-hook.js

@@ -0,0 +1,94 @@
+export function generateHookScript() {
+    return `#!/usr/bin/env node
+// Generated by: opentology context init
+// SessionStart hook — loads project context from OpenTology graph
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, resolve, dirname } from 'node:path';
+
+const TIMEOUT = parseInt(process.env.OPENTOLOGY_HOOK_TIMEOUT || '5000', 10);
+
+function findProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, '.opentology.json'))) return dir;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+function findBin(projectRoot) {
+  const local = join(projectRoot, 'node_modules', '.bin', 'opentology');
+  if (existsSync(local)) return { bin: local, args: [] };
+  return { bin: 'npx', args: ['opentology'] };
+}
+
+function run(projectRoot, cmdArgs) {
+  const { bin, args } = findBin(projectRoot);
+  return execFileSync(bin, [...args, ...cmdArgs], {
+    cwd: projectRoot,
+    timeout: TIMEOUT,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+function formatOutput(data) {
+  const lines = [];
+  lines.push(\`## Project Context: \${data.projectId}\\n\`);
+
+  if (data.sessions && data.sessions.length > 0) {
+    lines.push('### Recent Sessions');
+    for (const s of data.sessions) {
+      lines.push(\`- [\${s.date}] \${s.title}\`);
+      if (s.nextTodo) lines.push(\`  Next: \${s.nextTodo}\`);
+    }
+    lines.push('');
+  }
+
+  if (data.openIssues && data.openIssues.length > 0) {
+    lines.push(\`### Open Issues (\${data.openIssues.length})\`);
+    for (const i of data.openIssues) {
+      lines.push(\`- [\${i.date}] \${i.title}\`);
+    }
+    lines.push('');
+  }
+
+  if (data.recentDecisions && data.recentDecisions.length > 0) {
+    lines.push('### Recent Decisions');
+    for (const d of data.recentDecisions) {
+      lines.push(\`- [\${d.date}] \${d.title}\`);
+    }
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('Dependency graph (otx:Module + otx:dependsOn) is available in the context graph.');
+  lines.push('If significant code changes occurred since last scan, consider running opentology_context_scan to update dependency triples.');
+  lines.push('Reminder: At session end, push a session summary using opentology_push to the sessions graph.');
+
+  return lines.join('\\n');
+}
+
+try {
+  const projectRoot = findProjectRoot(process.cwd());
+  if (!projectRoot) process.exit(0);
+
+  const raw = run(projectRoot, ['context', 'load', '--format', 'json']);
+  const data = JSON.parse(raw);
+
+  const hasData = (data.sessions?.length > 0) ||
+                  (data.openIssues?.length > 0) ||
+                  (data.recentDecisions?.length > 0);
+
+  if (hasData) {
+    console.log(formatOutput(data));
+  } else {
+    console.log(\`OpenTology context active for \${data.projectId}. No session data yet.\`);
+  }
+} catch {
+  // Silent exit — do not block session start
+  process.exit(0);
+}
+`;
+}

package/dist/templates/slash-commands.d.ts

@@ -0,0 +1,5 @@
+export interface SlashCommand {
+    filename: string;
+    content: string;
+}
+export declare function generateSlashCommands(): SlashCommand[];

package/dist/templates/slash-commands.js

@@ -0,0 +1,108 @@
+export function generateSlashCommands() {
+    return [
+        {
+            filename: 'context-init.md',
+            content: `Use the opentology_context_init MCP tool to initialize the project context graph.
+
+After initialization:
+1. Report what was created (graphs, hook script, CLAUDE.md, slash commands).
+2. Show the hook JSON snippet the user needs to add to .claude/settings.json.
+
+## Codebase Analysis
+
+After context_init completes, call opentology_context_scan to get a codebase snapshot.
+
+Analyze the \`codebaseSnapshot\` field from the response and create Knowledge triples to push via \`opentology_push\`.
+
+### What to extract:
+- **Project triple** (\`otx:Project\`): name, description, tech stack (\`otx:stack\`), status "active"
+- **Knowledge triples** (\`otx:Knowledge\`): key architectural patterns, framework choices, build setup, project structure summary
+
+### Push instructions:
+- Push to the **context** graph (use graph name "context")
+- Use Turtle format with \`otx:\` and \`xsd:\` prefixes
+- Keep each push under 100 triples
+- Use URIs like \`urn:project:{name}\`, \`urn:knowledge:{slug}\`
+
+### Example triples:
+
+\`\`\`turtle
+@prefix otx: <https://opentology.dev/vocab#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<urn:project:{name}> a otx:Project ;
+    otx:title "{name}" ;
+    otx:date "{today}"^^xsd:date ;
+    otx:body "{description}" ;
+    otx:stack "{detected frameworks/languages}" ;
+    otx:status "active" .
+
+<urn:knowledge:project-structure> a otx:Knowledge ;
+    otx:title "Project Structure" ;
+    otx:date "{today}"^^xsd:date ;
+    otx:body "Entry points: ... Key directories: ... Build system: ..." ;
+    otx:relatedTo <urn:project:{name}> .
+\`\`\`
+
+### On subsequent runs (graph already populated):
+- Query existing Knowledge triples first
+- Update or add new triples for any changes detected
+- Do not duplicate existing knowledge
+`,
+        },
+        {
+            filename: 'context-load.md',
+            content: `Use the opentology_context_load MCP tool to load the current project context.
+
+Display the results in a readable format:
+- Recent sessions with dates and next todos
+- Open issues
+- Recent decisions
+
+If context is not initialized, suggest running /context-init first.
+`,
+        },
+        {
+            filename: 'context-save.md',
+            content: `Save a session summary to the OpenTology sessions graph.
+
+Ask the user what was accomplished in this session, or summarize the conversation so far.
+
+Then use opentology_push to insert a session record:
+
+\`\`\`turtle
+@prefix otx: <https://opentology.dev/vocab#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<urn:session:{today's date}> a otx:Session ;
+    otx:title "{session summary title}" ;
+    otx:date "{YYYY-MM-DD}"^^xsd:date ;
+    otx:body "{what was done}" ;
+    otx:nextTodo "{what to do next}" .
+\`\`\`
+
+Push to the sessions graph (use graph name "sessions").
+`,
+        },
+        {
+            filename: 'context-scan.md',
+            content: `Use the opentology_context_scan MCP tool to scan the current project codebase.
+
+The tool returns a structured \`codebaseSnapshot\` containing package.json, directory tree, entry points, detected imports, and README.
+
+Analyze the snapshot and create Knowledge triples to push via \`opentology_push\`:
+- **Project triple** (\`otx:Project\`): name, description, tech stack, status "active"
+- **Knowledge triples** (\`otx:Knowledge\`): architectural patterns, framework choices, build setup, project structure
+
+Push to the **context** graph (use graph name "context"). Keep each push under 100 triples.
+`,
+        },
+        {
+            filename: 'context-status.md',
+            content: `Use the opentology_context_status MCP tool to check the project context initialization status.
+
+Display the results clearly: whether context is initialized, graph triple counts, hook presence, and CLAUDE.md status.
+`,
+        },
+    ];
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "opentology",
+  "version": "0.1.0",
+  "description": "CLI-managed RDF/SPARQL infrastructure — Supabase for RDF",
+  "type": "module",
+  "bin": {
+    "opentology": "./dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node --esm src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "rdf",
+    "sparql",
+    "ontology",
+    "knowledge-graph",
+    "linked-data",
+    "shacl",
+    "cli",
+    "semantic-web"
+  ],
+  "author": "Younkyum Jin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Younkyum/opentology.git"
+  },
+  "homepage": "https://github.com/Younkyum/opentology#readme",
+  "bugs": {
+    "url": "https://github.com/Younkyum/opentology/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.3",
+    "n3": "^2.0.3",
+    "oxigraph": "^0.5.6",
+    "picocolors": "^1.1.1",
+    "rdf-ext": "^2.6.0",
+    "shacl-engine": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/n3": "^1.26.1",
+    "@types/node": "^25.5.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}