knowcode 0.1.0__tar.gz

knowcode-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,107 @@
+name: Publish KnowCode
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip build twine
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+
+  build-binaries:
+    name: Build & Publish NPM Binaries
+    strategy:
+      matrix:
+        include:
+          - os: windows-latest
+            pkg_name: knowcode-win32-x64
+            npm_os: win32
+            npm_cpu: x64
+            artifact_name: know.exe
+          - os: macos-latest
+            pkg_name: knowcode-darwin-arm64
+            npm_os: darwin
+            npm_cpu: arm64
+            artifact_name: know
+          - os: ubuntu-latest
+            pkg_name: knowcode-linux-x64
+            npm_os: linux
+            npm_cpu: x64
+            artifact_name: know
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          registry-url: "https://registry.npmjs.org"
+      - name: Install CLI and PyInstaller
+        run: |
+          pip install .
+          pip install pyinstaller
+      - name: Build executable
+        run: pyinstaller --name know --onefile src/runtime/cli/app.py
+      - name: Prepare NPM package
+        shell: bash
+        run: |
+          mkdir -p npm-binary-pkg/bin
+          mv dist/${{ matrix.artifact_name }} npm-binary-pkg/bin/
+          cat <<EOF > npm-binary-pkg/package.json
+          {
+            "name": "${{ matrix.pkg_name }}",
+            "version": "0.1.0",
+            "description": "Platform specific binary for KnowCode",
+            "os": [
+              "${{ matrix.npm_os }}"
+            ],
+            "cpu": [
+              "${{ matrix.npm_cpu }}"
+            ],
+            "author": "KnowCode Team",
+            "license": "MIT"
+          }
+          EOF
+      - name: Publish to NPM
+        working-directory: npm-binary-pkg
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public
+
+  publish-npm-wrapper:
+    name: Publish NPM Wrapper
+    needs: build-binaries
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          registry-url: "https://registry.npmjs.org"
+      - name: Publish Wrapper
+        working-directory: npm/knowcode
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

knowcode-0.1.0/.gitignore

@@ -0,0 +1,170 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# VS Code
+.vscode/
+
+# KnowCode Specific files
+knowcode.log
+.knowcode/
+.agent/
+knowiki.log
+knowcode.md

knowcode-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

knowcode-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: knowcode
+Version: 0.1.0
+Summary: Structural cognition engine for code repositories
+Requires-Python: >=3.13
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: ruamel-yaml>=0.18.0
+Requires-Dist: structlog>=25.0.0
+Requires-Dist: tree-sitter-javascript>=0.25.0
+Requires-Dist: tree-sitter-python>=0.25.0
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.25.2
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# KnowCode
+
+[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](#license)
+
+**KnowCode** is a structural cognition engine designed specifically for Agentic IDEs (like Cursor, Gemini, and Copilot). It bridges the gap between **physical repository code**, **deterministic structural snapshots**, and **semantic architectural knowledge**, allowing AI agents and human developers to seamlessly inspect, track, and maintain codebase architectures.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Usage: The Agentic Workflow](#usage-the-agentic-workflow)
+- [Ecosystem Layout](#ecosystem-layout)
+- [CLI Reference & Manual Execution](#cli-reference--manual-execution)
+- [License](#license)
+
+---
+
+## Overview
+
+KnowCode completely flips the traditional documentation model. Instead of forcing developers to write specs *before* they code, KnowCode uses an AI agent to track your intent during a development session. When you sync your physical code changes, the AI agent is automatically invoked to synthesize your intent against the deterministic reality of the codebase, ensuring your architectural knowledge naturally accumulates as a byproduct of development.
+
+KnowCode partitions codebase understanding into three clean domains:
+1. **Physical Reality:** The actual source files inside the repository.
+2. **Structural Truth:** Deterministic representation of files, components, and code symbols parsed via abstract syntax trees (ASTs).
+3. **Semantic Knowledge:** Permanent architectural rules, decisions, and constraints synthesized by your AI agent.
+
+---
+
+## Key Features
+
+- **Native Agent Integration:** Built-in slash commands (`/knowcode`, `/know-sync`) that plug directly into Agentic IDEs without configuration.
+- **Multi-Language AST Parsing**: Built on top of `tree-sitter`, with out-of-the-box support for **Python**, **JavaScript**, and **TypeScript**.
+- **Deterministic State & Revision Tracking**: Tracks codebase changes across sequential revisions (`S-001`, `S-002`, etc.).
+- **Diff & Report Generation**: Automatically computes additions, deletions, line-boundary modifications, and maps changes to their top-level affected components.
+
+---
+
+## Installation
+
+### Prerequisites
+- [Python 3.13+](https://www.python.org/)
+- [uv Package Manager](https://github.com/astral-sh/uv)
+
+### Installation
+
+You can install Knowcode directly via pip or npm.
+
+**Using pip:**
+```bash
+pip install knowcode
+```
+
+**Using npm:**
+```bash
+npm install -g knowcode
+```
+
+#### Development Setup
+
+If you want to contribute or modify the code, clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/knowiki/knowcode.git
+cd knowcode
+uv sync
+uv pip install -e .
+```
+
+---
+
+## Usage: The Agentic Workflow
+
+KnowCode is designed to be driven by you and your AI agent in tandem.
+
+### 1. Initialize the Repository
+Run the initialization command in your target repository terminal:
+```bash
+know .
+```
+This scaffolds the `.agent/` and `.knowcode/` directories, computes your first AST snapshot, and drops `knowcode.md` at your root. 
+
+*Note: To prevent polluting your repository, `know .` automatically adds `.knowcode/`, `.agent/`, and `knowcode.md` to your `.gitignore`. If you want to share your synthesized semantic knowledge with your team, you can selectively un-ignore `.knowcode/knowledge/`.*
+
+### 2. Activate the Agent
+In your AI chat (Cursor, Copilot, Gemini), simply type:
+```text
+/knowcode
+```
+The agent will instantly read `knowcode.md`, lock into the KnowCode governance rules, and begin silently tracking your intent in `.agent/memory/active_context.md` while you code.
+
+### 3. Sync & Synthesize
+After you finish a coding session or fix a bug, instruct the agent to synchronize by typing:
+```text
+/know-sync
+```
+The agent will orchestrate the entire lifecycle:
+1. Run `know sync` to compute structural AST diffs.
+2. Read the generated structural report (`R-XXX.md`).
+3. Reconcile the structural reality against your tracked intent.
+4. Distribute the extracted knowledge into the 5 semantic buckets (`architecture`, `decisions`, etc.).
+5. Run `know sync-semantic` to commit the knowledge and bump the revision.
+
+---
+
+## Ecosystem Layout
+
+When KnowCode is initialized in a repository via `know .`, it generates a governed agent architecture:
+
+```text
+/
+├── knowcode.md                # The Agent Ignition Switch (Read by the AI)
+├── .agent/                    # The Semantic Governance & Memory Layer
+│   ├── memory/
+│   │   ├── active_context.md  # The AI's short-term intent tracking buffer
+│   │   └── previous_context.md
+│   ├── skills/
+│   │   ├── track_intent.md    # Background skill for tracking architectural intent
+│   │   └── synthesize_knowledge.md
+│   └── workflows/
+│       ├── sync_reconciliation.md # The /know-sync workflow
+│       └── ingest_legacy.md       # The /know-ingest workflow
+│
+└── .knowcode/                 # The Deterministic Knowledge Artifact
+    ├── state.yaml             # Authoritative state registry (managed by the Engine)
+    ├── structure/             # Deterministic AST snapshots (e.g. S-001.json)
+    ├── reports/               # Change and diff analysis reports (e.g. R-001.md)
+    └── knowledge/             # Permanent semantic knowledge (AI synthesized)
+        ├── architecture/
+        ├── components/
+        ├── constraints/
+        ├── conventions/
+        ├── decisions/
+        └── raw/               # Inbox for legacy or unstructured documentation
+```
+
+---
+
+## CLI Reference & Manual Execution
+
+While the Agentic Workflow relies on slash commands to orchestrate operations, developers can bypass the AI entirely and execute any step manually using the `know` CLI. This is useful for CI/CD pipelines, programmatic integration, or direct inspection.
+
+- `know .`: Initializes Knowcode in the current directory.
+- `know status`: Displays current structural and semantic revisions.
+- `know sync`: Computes AST diffs, generates a report, and rolls over the memory buffer.
+- `know sync-semantic`: Bumps the semantic revision after the AI (or a human) finishes synthesis.
+- `know ingest-semantic .`: Wipes the raw documentation inbox and bumps the revision.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

knowcode-0.1.0/README.md

@@ -0,0 +1,156 @@
+# KnowCode
+
+[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](#license)
+
+**KnowCode** is a structural cognition engine designed specifically for Agentic IDEs (like Cursor, Gemini, and Copilot). It bridges the gap between **physical repository code**, **deterministic structural snapshots**, and **semantic architectural knowledge**, allowing AI agents and human developers to seamlessly inspect, track, and maintain codebase architectures.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Usage: The Agentic Workflow](#usage-the-agentic-workflow)
+- [Ecosystem Layout](#ecosystem-layout)
+- [CLI Reference & Manual Execution](#cli-reference--manual-execution)
+- [License](#license)
+
+---
+
+## Overview
+
+KnowCode completely flips the traditional documentation model. Instead of forcing developers to write specs *before* they code, KnowCode uses an AI agent to track your intent during a development session. When you sync your physical code changes, the AI agent is automatically invoked to synthesize your intent against the deterministic reality of the codebase, ensuring your architectural knowledge naturally accumulates as a byproduct of development.
+
+KnowCode partitions codebase understanding into three clean domains:
+1. **Physical Reality:** The actual source files inside the repository.
+2. **Structural Truth:** Deterministic representation of files, components, and code symbols parsed via abstract syntax trees (ASTs).
+3. **Semantic Knowledge:** Permanent architectural rules, decisions, and constraints synthesized by your AI agent.
+
+---
+
+## Key Features
+
+- **Native Agent Integration:** Built-in slash commands (`/knowcode`, `/know-sync`) that plug directly into Agentic IDEs without configuration.
+- **Multi-Language AST Parsing**: Built on top of `tree-sitter`, with out-of-the-box support for **Python**, **JavaScript**, and **TypeScript**.
+- **Deterministic State & Revision Tracking**: Tracks codebase changes across sequential revisions (`S-001`, `S-002`, etc.).
+- **Diff & Report Generation**: Automatically computes additions, deletions, line-boundary modifications, and maps changes to their top-level affected components.
+
+---
+
+## Installation
+
+### Prerequisites
+- [Python 3.13+](https://www.python.org/)
+- [uv Package Manager](https://github.com/astral-sh/uv)
+
+### Installation
+
+You can install Knowcode directly via pip or npm.
+
+**Using pip:**
+```bash
+pip install knowcode
+```
+
+**Using npm:**
+```bash
+npm install -g knowcode
+```
+
+#### Development Setup
+
+If you want to contribute or modify the code, clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/knowiki/knowcode.git
+cd knowcode
+uv sync
+uv pip install -e .
+```
+
+---
+
+## Usage: The Agentic Workflow
+
+KnowCode is designed to be driven by you and your AI agent in tandem.
+
+### 1. Initialize the Repository
+Run the initialization command in your target repository terminal:
+```bash
+know .
+```
+This scaffolds the `.agent/` and `.knowcode/` directories, computes your first AST snapshot, and drops `knowcode.md` at your root. 
+
+*Note: To prevent polluting your repository, `know .` automatically adds `.knowcode/`, `.agent/`, and `knowcode.md` to your `.gitignore`. If you want to share your synthesized semantic knowledge with your team, you can selectively un-ignore `.knowcode/knowledge/`.*
+
+### 2. Activate the Agent
+In your AI chat (Cursor, Copilot, Gemini), simply type:
+```text
+/knowcode
+```
+The agent will instantly read `knowcode.md`, lock into the KnowCode governance rules, and begin silently tracking your intent in `.agent/memory/active_context.md` while you code.
+
+### 3. Sync & Synthesize
+After you finish a coding session or fix a bug, instruct the agent to synchronize by typing:
+```text
+/know-sync
+```
+The agent will orchestrate the entire lifecycle:
+1. Run `know sync` to compute structural AST diffs.
+2. Read the generated structural report (`R-XXX.md`).
+3. Reconcile the structural reality against your tracked intent.
+4. Distribute the extracted knowledge into the 5 semantic buckets (`architecture`, `decisions`, etc.).
+5. Run `know sync-semantic` to commit the knowledge and bump the revision.
+
+---
+
+## Ecosystem Layout
+
+When KnowCode is initialized in a repository via `know .`, it generates a governed agent architecture:
+
+```text
+/
+├── knowcode.md                # The Agent Ignition Switch (Read by the AI)
+├── .agent/                    # The Semantic Governance & Memory Layer
+│   ├── memory/
+│   │   ├── active_context.md  # The AI's short-term intent tracking buffer
+│   │   └── previous_context.md
+│   ├── skills/
+│   │   ├── track_intent.md    # Background skill for tracking architectural intent
+│   │   └── synthesize_knowledge.md
+│   └── workflows/
+│       ├── sync_reconciliation.md # The /know-sync workflow
+│       └── ingest_legacy.md       # The /know-ingest workflow
+│
+└── .knowcode/                 # The Deterministic Knowledge Artifact
+    ├── state.yaml             # Authoritative state registry (managed by the Engine)
+    ├── structure/             # Deterministic AST snapshots (e.g. S-001.json)
+    ├── reports/               # Change and diff analysis reports (e.g. R-001.md)
+    └── knowledge/             # Permanent semantic knowledge (AI synthesized)
+        ├── architecture/
+        ├── components/
+        ├── constraints/
+        ├── conventions/
+        ├── decisions/
+        └── raw/               # Inbox for legacy or unstructured documentation
+```
+
+---
+
+## CLI Reference & Manual Execution
+
+While the Agentic Workflow relies on slash commands to orchestrate operations, developers can bypass the AI entirely and execute any step manually using the `know` CLI. This is useful for CI/CD pipelines, programmatic integration, or direct inspection.
+
+- `know .`: Initializes Knowcode in the current directory.
+- `know status`: Displays current structural and semantic revisions.
+- `know sync`: Computes AST diffs, generates a report, and rolls over the memory buffer.
+- `know sync-semantic`: Bumps the semantic revision after the AI (or a human) finishes synthesis.
+- `know ingest-semantic .`: Wipes the raw documentation inbox and bumps the revision.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

knowcode-0.1.0/npm/knowcode/bin/know.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+const { spawnSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+
+const platform = os.platform(); // 'win32', 'darwin', 'linux'
+const arch = os.arch();         // 'x64', 'arm64'
+
+const packageMap = {
+  'win32-x64': 'knowcode-win32-x64',
+  'darwin-arm64': 'knowcode-darwin-arm64',
+  'linux-x64': 'knowcode-linux-x64'
+};
+
+const key = `${platform}-${arch}`;
+const targetPackageName = packageMap[key];
+
+if (!targetPackageName) {
+  console.error(`Unsupported platform/architecture: ${key}`);
+  process.exit(1);
+}
+
+try {
+  const binaryName = platform === 'win32' ? 'know.exe' : 'know';
+  const binaryPath = require.resolve(`${targetPackageName}/bin/${binaryName}`);
+
+  // Set the environment variable to identify npm install method
+  process.env.KNOWCODE_INSTALL_METHOD = 'npm';
+
+  const result = spawnSync(binaryPath, process.argv.slice(2), {
+    stdio: 'inherit',
+    windowsHide: true
+  });
+
+  process.exit(result.status ?? 0);
+} catch (err) {
+  console.error(`Error: Failed to execute KnowCode CLI binary.
+Details: ${err.message}
+Please ensure that the platform-specific dependency '${targetPackageName}' is installed correctly.`);
+  process.exit(1);
+}

knowcode-0.1.0/npm/knowcode/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "knowcode",
+  "version": "0.1.0",
+  "description": "KnowCode : the knowledge layer to your code",
+  "bin": {
+    "know": "bin/know.js"
+  },
+  "files": [
+    "bin/know.js"
+  ],
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "author": "KnowCode Team",
+  "license": "MIT",
+  "optionalDependencies": {
+    "knowcode-win32-x64": "0.1.0",
+    "knowcode-darwin-arm64": "0.1.0",
+    "knowcode-linux-x64": "0.1.0"
+  }
+}