getting-started.md

Getting Started with LogicStamp Context

Welcome to LogicStamp Context - the context compiler for TypeScript. This guide will help you compile your codebase into deterministic architectural contracts for AI workflows.

What is LogicStamp Context?

LogicStamp Context compiles TypeScript codebases into deterministic architectural contracts and dependency graphs. Instead of AI assistants parsing raw source code, they consume a structured, machine-consumable representation that explicitly describes:

• Component props and their types
• Hooks and state management
• Dependencies and relationships
• API signatures (for backend code)
• Style metadata (optional)

Key benefits:

• ✅ Deterministic - Same code always produces the same contracts
• ✅ Structured - Pre-parsed contracts, not raw source code
• ✅ Framework-aware - Understands React, Next.js, Vue, Express, NestJS
• ✅ Watch mode - Auto-regenerates as you code
• ✅ Strict watch - Detects breaking changes during development
• ✅ MCP-ready - Works seamlessly with AI assistants via MCP protocol

Relationship to TypeScript (tsc)

LogicStamp is additive: it produces architectural contracts and graphs for AI workflows and diffs, alongside your normal toolchain. Keep tsc --noEmit (or your CI typecheck) for program-wide type errors—your tsconfig and compiler pipeline stay the authority there.

Beyond .d.ts: Declaration files capture surfaces for consumers; LogicStamp adds semantic contracts, dependency relationships, and change hashes (semanticHash/bundleHash) for diffable LLM context.

Strict modes (stamp context compare --strict, stamp context --strict-watch) detect contract-level breaking changes (e.g. removed props) against a baseline—they do not replicate the full TypeScript checker.

Backend (Express / NestJS) vs tsc: The compiler checks types in handlers and DTOs, not HTTP wiring. Renaming a path or method while types stay the same often produces no tsc error, but it does break external callers. LogicStamp records routes, methods, and related metadata in contracts and in semanticHash, so stamp context compare (and watch) can show that drift in diffs. Strict modes today focus on removals like props, events, exported functions, or whole contracts; route and API-signature changes usually appear in compare output and hashes first—see API signature handling in strict modes.

For how extraction differs from your project compiler settings (e.g. path aliases), see TypeScript support.

Choose Your Path

LogicStamp Context can be used in two ways:

🖥️ CLI Usage - For Developers

Use the command-line interface to generate context files that you can share with AI assistants or use in your workflows.

Best for:

• Generating context files manually
• CI/CD pipelines
• Sharing context with team members
• Custom automation scripts

👉 Start with CLI →

🤖 MCP Server - For AI Assistants

Install the MCP server to give AI assistants (Claude Desktop, Cursor) direct access to your codebase context.

Best for:

• Using Claude Desktop or Cursor AI
• Real-time context access for AI assistants
• Automatic context updates via watch mode
• Seamless AI workflow integration

👉 Start with MCP → (MCP server documentation)

Quick Start (30 seconds)

Want to try it right now? No installation required:

npx logicstamp-context context

This will:

1. Scan your TypeScript codebase
2. Generate context.json files (one per folder)
3. Create context_main.json index file

What you get:

• 📁 context.json files - Component contracts organized by folder
• 📋 context_main.json - Project overview and folder metadata

How It Works

TypeScript Code  →  AST Parsing  →  Deterministic Contracts  →  AI Assistant
   (.ts/.tsx)        (ts-morph)      (context.json bundles)      (Claude, Cursor)

1. Scan - Finds all .ts and .tsx files in your project
2. Analyze - Parses components and APIs using TypeScript AST (via ts-morph)
3. Extract - Builds contracts with props, hooks, state, signatures
4. Graph - Creates dependency graph showing relationships
5. Bundle - Packages context optimized for AI workflows
6. Organize - Groups by folder, writes context.json files
7. Index - Creates context_main.json with metadata and statistics

Example Output

LogicStamp Context generates structured JSON bundles:

{
  "type": "LogicStampBundle",
  "entryId": "src/components/Button.tsx",
  "graph": {
    "nodes": [
      {
        "entryId": "src/components/Button.tsx",
        "contract": {
          "kind": "react:component",
          "interface": {
            "props": {
              "variant": { "type": "literal-union", "literals": ["primary", "secondary"] },
              "onClick": { "type": "function", "signature": "() => void" }
            }
          },
          "composition": {
            "hooks": ["useState"],
            "components": ["./Icon"]
          }
        }
      }
    ],
    "edges": [["src/components/Button.tsx", "./Icon"]]
  }
}

📋 See Schema Documentation for complete format details.

Requirements

• Node.js >= 20
• TypeScript codebase (React, Next.js, Vue, Express, or NestJS)

Framework Support

Framework	Support Level	What's Extracted
React	Full	Components, hooks, props, styles
Next.js	Full	App Router roles, segment paths, metadata
Vue 3	Partial	Composition API (TS/TSX only, not .vue SFC)
Express.js	Full	Routes, API signatures (middleware not extracted; see limitations)
NestJS	Full	Controllers, decorators, API signatures
UI Libraries	Full	Material UI, ShadCN, Radix, Tailwind, Styled Components, SCSS, Chakra UI, Ant Design

ℹ️ Note: LogicStamp Context analyzes .ts and .tsx files only. JavaScript files are not analyzed.

Next Steps

For CLI Users

1. CLI Getting Started Guide - Complete CLI setup and usage
2. Usage Guide - Comprehensive command reference
3. Watch Mode - Auto-regenerate context as you code (includes strict watch mode)
4. Schema Documentation - Understanding output format

For MCP Users

1. MCP Getting Started Guide - MCP server setup
2. CLI Getting Started Guide - Understanding the underlying CLI
3. Watch Mode - Keep context fresh automatically

Common Workflows

Development Workflow

# Initialize project
stamp init

# Start watch mode (auto-regenerates on changes)
stamp context --watch

# Strict watch mode (detects breaking changes during refactors)
stamp context --strict-watch

# Generate with style metadata
stamp context style

CI/CD Workflow

# Generate context in CI
stamp context --profile ci-strict --strict-missing

# Validate context files
stamp context validate

# Compare for drift detection
stamp context compare

AI Assistant Workflow

# Generate context for AI
stamp context --profile llm-chat

# Or use MCP server for automatic access
# (See MCP Getting Started Guide)

Security

LogicStamp Context includes automatic secret protection:

• Security scanning - stamp init scans for secrets (API keys, passwords, tokens)
• Automatic sanitization - Detected secrets replaced with "PRIVATE_DATA" in output
• Safe by default - Only metadata included. Credentials only appear in --include-code full mode

🔒 See Security Documentation for complete security details.

Need Help?

• Issues - GitHub Issues
• Documentation - Full Documentation Index
• Roadmap - logicstamp.dev/roadmap

What's Next?

• New to LogicStamp? → Start with CLI Getting Started
• Using AI Assistants? → Check out MCP Getting Started
• Want to understand output? → Read Schema Documentation
• Need command reference? → See Usage Guide

---

Ready to get started? Choose your path above or jump to the Quick Start section!