aisquare-cli 0.1.0__tar.gz

aisquare_cli-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What & why
+
+<!-- What does this change do, and why? Link any related issue. -->
+
+## How to verify
+
+<!-- Commands run, behaviour observed. -->
+
+## Checklist
+
+- [ ] `make check` passes locally (lint + typecheck + tests)
+- [ ] Added or updated tests for the change
+- [ ] If a command graduated from stub to real, it's removed from the
+      `IMPLEMENTED` skip-list in `tests/test_stubs.py` and has its own tests
+- [ ] Updated docs (README / CONTRIBUTING) if behaviour or commands changed

aisquare_cli-0.1.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  # Keep GitHub Actions pinned actions current.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+
+  # Keep Python dependencies current.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: deps

aisquare_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Cancel superseded runs on the same branch/PR.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: check (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src tests
+
+      - name: Format check (ruff)
+        run: ruff format --check src tests
+
+      - name: Type check (mypy)
+        run: mypy
+
+      - name: Test (pytest)
+        run: pytest -ra
+
+  package:
+    name: package (build + install)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Install the wheel in a clean environment
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install dist/*.whl
+      - name: Smoke-test the console scripts
+        run: |
+          /tmp/smoke/bin/aisquare --version
+          /tmp/smoke/bin/asq --version
+          /tmp/smoke/bin/aisquare --help

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

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no API token/secret needed.
+# Triggered when a GitHub Release is published. The version that ships is whatever
+# is in pyproject.toml, so bump it before tagging the release.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

aisquare_cli-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/

aisquare_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to aisquare
+
+Thanks for your interest in aisquare! This is an early-stage, open-source
+project and contributions are welcome.
+
+## Development setup
+
+Requires Python 3.11+.
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+make install          # editable install + dev tools (ruff, mypy, pytest)
+```
+
+## Before you open a PR
+
+Run the full check suite — this is exactly what CI runs:
+
+```sh
+make check            # lint + typecheck + tests
+```
+
+Individual targets:
+
+| Task | Command |
+| --- | --- |
+| Format + autofix | `make fmt` |
+| Lint | `make lint` |
+| Type-check (mypy strict) | `make typecheck` |
+| Tests | `make test` |
+
+CI (`.github/workflows/ci.yml`) runs lint, format-check, mypy and pytest on
+Python 3.11–3.13, plus a packaging job that builds the wheel and smoke-tests the
+`aisquare` / `asq` console scripts. All jobs must pass before a PR can merge.
+
+## Implementing a feature (stub → service)
+
+Most commands are still stubs that exit `70`. Each one becomes real by replacing
+a single `stub(...)` call in a `services/` module — the CLI wiring and function
+signatures already exist. The flow is:
+
+1. **Implement the service** in `src/aisquare/services/<domain>.py`. Services
+   return data; they never parse CLI arguments or print. Persisted state goes
+   through the `ContextStore` in `src/aisquare/core/store.py`.
+2. **Render it** in the matching `src/aisquare/cli/<group>.py` command: parse,
+   call the service, print (honouring `--json` via `get_state().json_output`).
+   Shared rendering helpers live in `cli/common.py`.
+3. **Move the command off the stub skip-list** in `tests/test_stubs.py`
+   (`IMPLEMENTED`) and add real tests for the new behaviour.
+
+See the README's [Architecture](README.md#architecture) section for the full
+layout and the thin-CLI / service / core split.
+
+## Conventions
+
+- **Type everything.** `mypy` runs in `strict` mode over `src` and `tests`.
+- **Tests are isolated.** The `isolated_home` fixture points `AISQUARE_HOME` at
+  a temp dir, so tests never touch your real `~/.aisquare`. Never write to the
+  real home in a test or example.
+- Keep CLI modules thin and services free of CLI concerns.
+- New shared plumbing goes in `core/`; new domain shapes go in `models.py`.
+
+## Reporting bugs / proposing features
+
+Open an issue describing what you expected and what happened. For larger
+changes, it's worth opening an issue to discuss the approach before writing
+code.

aisquare_cli-0.1.0/LICENSE

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

aisquare_cli-0.1.0/Makefile

@@ -0,0 +1,25 @@
+.PHONY: install test lint typecheck fmt check
+
+## install: editable install with dev tools (run inside a virtualenv)
+install:
+	pip install -e ".[dev]"
+
+## test: run the test suite
+test:
+	pytest
+
+## lint: static checks without modifying files
+lint:
+	ruff check src tests
+
+## typecheck: run mypy over src and tests
+typecheck:
+	mypy
+
+## fmt: auto-format and auto-fix lint findings
+fmt:
+	ruff format src tests
+	ruff check --fix src tests
+
+## check: everything CI would run
+check: lint typecheck test

aisquare_cli-0.1.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: aisquare-cli
+Version: 0.1.0
+Summary: Portable memory layer for coding agents — persistent user and project context across sessions.
+Project-URL: Homepage, https://aisquare.studio
+Project-URL: Repository, https://github.com/AISquare-Studio/aisquare-cli
+Project-URL: Issues, https://github.com/AISquare-Studio/aisquare-cli/issues
+Author-email: AISquare <anmol@aisquare.studio>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,cli,context,memory
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.26.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aisquare
+
+**Portable memory layer for coding agents.** `aisquare` installs into agents
+like Claude Code and keeps their context — your preferences and each project's
+conventions — persistent across sessions and machines.
+
+> **Status: early.** The full command surface exists and parses arguments.
+> Implemented and backed by a local SQLite store: `init`, `remember`, the full
+> `context` group, `inject`/`why`, the `project` group (incl. a **Repomix
+> codebase snapshot**), `status`/`doctor`, the `config` group, `log`, and the
+> `agents` group — which **installs into Claude Code** (see
+> [Claude Code integration](#claude-code-integration)). The remaining commands
+> (`auth`/cloud, `capture`, `sync`, `connectors`, `policy`) are stubs: each
+> prints `⚠ aisquare <command> is not implemented yet (planned: <tier>)` to
+> stderr and exits `70`. Features land one service module at a time — see
+> [Implementing a feature](#implementing-a-feature-stub--service).
+
+## Implemented
+
+```sh
+aisquare init                    # set up ~/.aisquare, register & onboard this project
+aisquare remember "prefer pytest over unittest" --user --tag testing
+aisquare context add "run make check before pushing" --project
+aisquare context list            # user pool + the active project's pool
+aisquare context search pytest   # full-text search (SQLite FTS5)
+aisquare context show a3f2       # by id or unambiguous prefix (git-style)
+aisquare context edit a3f2       # opens the entry in $EDITOR
+aisquare context promote a3f2    # move a project entry into the user pool
+aisquare context remove a3f2     # soft-delete (tombstoned)
+aisquare context export out.md   # export in-scope context (md or --format json)
+aisquare context import notes.md # seed context from Markdown bullets or JSON
+aisquare context preview         # the context block that would be injected
+aisquare inject                  # emit that block (and record the injection)
+aisquare why                     # explain the last injection
+aisquare project list            # registered projects (active one marked *)
+aisquare project switch alpha    # pin the active project (name or id prefix)
+aisquare project onboard         # pack a Repomix snapshot + seed ecosystem facts
+aisquare agents scan             # detect installed agents (Claude Code, …)
+aisquare agents connect claude-code  # install hooks + ingest CLAUDE.md
+aisquare log                     # captured prompt history for this project
+aisquare status                  # health, pools, active project, agents
+aisquare doctor                  # checks deps/install/hooks/snapshot + how to fix each
+aisquare config set default_pool user   # read/write config (get/list/redaction)
+aisquare --json context list     # machine-readable output (any command)
+```
+
+Context lives in two pools — `user` (global) and `project` — persisted in a
+SQLite database at `~/.aisquare/context.db`. The **active project** is whichever
+you `project switch` to (pinned in `state.json`), else the one containing your
+working directory; everything scopes to it consistently. Entries carry
+sync-ready metadata (`updated_at`, soft-delete tombstones) and time-sortable,
+prefix-addressable ids from day one.
+
+## Claude Code integration
+
+`aisquare agents connect claude-code` makes aisquare an active part of Claude
+Code by writing two hooks into `~/.claude/settings.json` (merged, never
+clobbering your other settings; remove them with `agents disconnect`):
+
+- **`SessionStart` → `aisquare hook session-start`** — injects a directive that
+  points Claude at the codebase snapshot (skeleton first, full pack on demand)
+  and the prompt history, plus your in-scope context — so Claude orients without
+  burning tokens grepping for files.
+- **`UserPromptSubmit` → `aisquare hook user-prompt-submit`** — captures how you
+  prompt, so Claude can replay your intent (`aisquare log`).
+
+The **codebase snapshot** (`project onboard`, or `init`) mirrors the server-side
+[Repomix](https://github.com/yamadashy/repomix) packing for sync-consistency: a
+full pack (`repomix --style xml`), a skeleton (`--compress`), and a per-file
+index (char offsets + token counts), stored under
+`~/.aisquare/projects/<id>/snapshot/`. Requires Node + repomix on PATH (run via
+`npx` otherwise); if neither is present the snapshot is skipped, not fatal.
+
+## Requirements
+
+- Python 3.11+
+- Optional, for codebase snapshots: Node.js + [repomix](https://github.com/yamadashy/repomix) (or it runs via `npx`)
+
+## Install
+
+```sh
+pipx install aisquare-cli     # recommended — isolated, stable `aisquare` / `asq` on PATH
+# or:  pip install aisquare-cli
+```
+
+Installs two equivalent commands: `aisquare` and `asq`. The PyPI distribution is
+**`aisquare-cli`** (the `aisquare` name belongs to the AISquare SDK); the command
+stays `aisquare`. `pipx` is recommended so the Claude Code hook keeps a stable
+path. Run `aisquare doctor` to see what's set up and what's missing.
+
+## Install (development)
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+make install          # = pip install -e ".[dev]"
+```
+
+## Quick check
+
+```sh
+aisquare --help
+aisquare --version
+aisquare doctor              # install/deps/integration health
+asq ctx list                 # aliases work too
+```
+
+## Command tree
+
+```
+aisquare
+├── init [path] [--api-key K] [--local] [--agent A]... [--no-onboard] [--reinit] [-y]
+├── status · doctor · inject · sync · why · log · open
+├── remember <text> [--user|--project] [--tag T]...
+├── login · logout · whoami · upgrade · uninstall
+├── auth        status · rotate · token
+├── agents      list · connect <name> · disconnect <name> · scan · status [name]
+├── connectors  list · add <name> · remove <name> · status
+├── context     list · add <text> [--user|--project] [--tag T]... · show <id> · edit <id>
+│   (alias ctx) remove <id> · search <query> · preview · import <file>
+│               export [file] [--format md|json] · promote <id>
+├── project     info · list · switch <name> · link <repo> · onboard [path] [--refresh]
+│   (alias workspace)
+├── capture     status · pause · resume · start · stop
+├── config      list · get <key> · set <key> <value> · redaction <off|standard|strict>
+├── policy      list
+└── enforce     status · enable · disable
+```
+
+### Global flags
+
+| Flag | Meaning |
+| --- | --- |
+| `-V`, `--version` | Print the version and exit |
+| `-v`, `--verbose` | Verbose output |
+| `-q`, `--quiet` | Suppress non-essential output |
+| `--json` | Machine-readable JSON on stdout |
+| `--profile NAME` | Configuration profile to use |
+| `--no-color` | Disable coloured output |
+
+Global flags go **before** the command: `aisquare --json context list`.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `2` | Usage error (bad arguments) |
+| `70` | Command not implemented yet |
+
+## Architecture
+
+```
+src/aisquare/
+├── cli/          # THIN Typer layer: one module per command group.
+│   │             # Parses arguments, then calls exactly one service function.
+│   ├── app.py    # root app: global flags, --version, group registration
+│   ├── root.py   # top-level commands (init, status, remember, ...)
+│   ├── common.py # shared parsing helpers (e.g. --user/--project → pool)
+│   └── <group>.py
+├── services/     # SERVICE layer: one module per domain. Real behaviour goes
+│   │             # here. Today every function raises the shared stub.
+│   └── <domain>.py
+├── core/         # shared infrastructure (already real):
+│   ├── paths.py  #   ~/.aisquare layout (override with $AISQUARE_HOME)
+│   ├── config.py #   typed TOML config load/save (Pydantic + tomllib/tomli-w)
+│   ├── store.py  #   SQLite context store (ContextStore protocol + open_store)
+│   ├── ids.py    #   ULID-style, time-sortable, prefix-addressable entry ids
+│   ├── entries.py#   shared ContextEntry factory (add / import / onboard)
+│   ├── workspace.py #  resolve the active project (pin in state.json, else cwd)
+│   ├── injection.py #  assemble the context block + record injections (why)
+│   ├── agents.py #   detect agents + install Claude Code hooks (settings.json)
+│   ├── snapshot.py #  Repomix codebase pack (full + skeleton + index)
+│   ├── editor.py #   launch $EDITOR for `context edit`
+│   ├── state.py  #   runtime state from the global flags
+│   ├── console.py#   Rich console factories honouring --no-color
+│   └── stubs.py  #   stub() — the consistent not-implemented behaviour
+└── models.py     # Pydantic domain models (ContextEntry, DataEnvelope, ...)
+```
+
+Flow: `cli/<group>.py` parses arguments → calls `services/<domain>.py` →
+(today) `core/stubs.py:stub()` prints the not-implemented message and raises
+`typer.Exit(70)`.
+
+**What is real today:** `--help` everywhere, `--version`, global-flag parsing
+into `core/state.py`, the `~/.aisquare/` layout, TOML config load/save, the
+SQLite context store (`core/store.py`), and the commands wired to it — `init`,
+`remember`, the full `context` group (`add`, `list`, `show`, `edit`, `remove`,
+`search`, `promote`, `import`, `export`, `preview`), `inject`, `why`, the
+`project` group (`info`, `list`, `switch`, `link`, `onboard`+snapshot),
+`status`, `doctor`, the `config` group (`list`, `get`, `set`, `redaction`),
+`log`, and the `agents` group (`scan`, `list`, `status`, `connect`+hooks,
+`disconnect`). Everything else is a stub.
+
+### `~/.aisquare/` layout
+
+```
+~/.aisquare/
+├── config.toml   # typed configuration (core/config.py)
+├── credentials   # API keys / tokens
+├── context.db    # SQLite store: context entries, projects, captured prompts
+├── state.json    # small runtime state (e.g. the pinned active project)
+├── agents.json   # registry of connected agents
+├── projects/     # per-project data — <id>/snapshot/ (Repomix pack + skeleton + index)
+├── cache/        # disposable cached data (e.g. last_injection.json)
+└── log/          # capture and diagnostic logs
+```
+
+Set `AISQUARE_HOME` to relocate the whole tree (the test suite does this).
+
+## Implementing a feature (stub → service)
+
+Each feature is implemented by replacing one `stub(...)` call in one service
+module. The CLI wiring, argument parsing and signatures already exist. Example —
+making `aisquare context add` real:
+
+**1. Implement the service** (`src/aisquare/services/context.py`). Replace the
+stub with real logic; keep the existing signature, it is already final.
+Persisted state goes through the `ContextStore` from `core/store.py`. The
+already-implemented `add_entry` is the worked example:
+
+```python
+def add_entry(text: str, pool: Pool | None, tags: list[str]) -> ContextEntry:
+    """Add a context entry to the user or project pool."""
+    resolved: Pool = pool or load_config().default_pool
+    with store_session() as store:
+        project_id: str | None = None
+        if resolved == "project":
+            project = current_project()
+            store.ensure_project(project)
+            project_id = project.id
+        now = datetime.now(tz=UTC)
+        entry = ContextEntry(
+            id=new_entry_id(), pool=resolved, project_id=project_id, text=text,
+            tags=tags, source="cli", created_at=now, updated_at=now,
+        )
+        return store.add(entry)
+```
+
+**2. Render in the CLI layer** (`src/aisquare/cli/context.py`). The CLI module
+stays thin: parse, call the service, print. Honour `--json` via the runtime
+state:
+
+```python
+@app.command("add")
+def add(text: ..., user: ..., project: ..., tag: ...) -> None:
+    """Add a context entry."""
+    entry = context_service.add_entry(text, pool=resolve_pool(user, project), tags=tag or [])
+    if get_state().json_output:
+        typer.echo(entry.model_dump_json())
+    else:
+        stdout_console().print(f"✓ remembered ({entry.pool}): {entry.text}")
+```
+
+**3. Update the tests.** The walk-based test in `tests/test_stubs.py` asserts
+that every leaf exits with `70`; once a command is real it will fail there —
+add the command to an explicit "implemented" skip-list in that test and write
+real tests for the new behaviour.
+
+Rules of thumb:
+
+- CLI modules never contain behaviour; services never parse CLI arguments.
+- Services return data; the CLI renders it. (`stub()` printing is the one
+  deliberate exception, so all unimplemented commands behave identically.)
+- New shared plumbing goes in `core/`; new domain shapes go in `models.py`.
+
+## Development
+
+| Task | Command |
+| --- | --- |
+| Install (editable + dev tools) | `make install` |
+| Run tests | `make test` |
+| Lint | `make lint` |
+| Type-check | `make typecheck` |
+| Format + autofix | `make fmt` |
+| All CI checks | `make check` |
+
+Run a single test: `pytest tests/test_stubs.py -k "context add"`.