austial-cli 0.1.5__tar.gz → 0.2.0__tar.gz

{austial_cli-0.1.5 → austial_cli-0.2.0}/.gitignore

@@ -9,3 +9,4 @@ htmlcov/
 dist/
 build/
 *.egg-info/
+.DS_Store

{austial_cli-0.1.5 → austial_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: austial-cli
-Version: 0.1.5
+Version: 0.2.0
 Summary: The `austial` scaffolding CLI (new/generate) and its Jinja2 project templates -- mirrors the separate @nestjs/cli repo.
 Requires-Python: >=3.11
 Requires-Dist: jinja2>=3.1.0

austial_cli-0.2.0/src/austial/cli/generators/agent_files.py

@@ -0,0 +1,45 @@
+"""AI-tool instruction files for a new project.
+
+One canonical ``AGENTS.md`` is written, and every other tool's instructions
+file is a symlink to it, so there is a single file to edit and no drift. Where
+the filesystem can't create symlinks (Windows without Developer Mode), the
+file is copied instead. See https://docs.austial.com/ai/setup.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+AGENTS_FILE = "AGENTS.md"
+
+# link path (relative to the project root) -> symlink target (relative to the link's own directory)
+AGENT_LINKS: dict[str, str] = {
+    "CLAUDE.md": "AGENTS.md",
+    "GEMINI.md": "AGENTS.md",
+    "CONVENTIONS.md": "AGENTS.md",
+    ".windsurfrules": "AGENTS.md",
+    ".clinerules": "AGENTS.md",
+    ".rules": "AGENTS.md",
+    ".github/copilot-instructions.md": "../AGENTS.md",
+}
+
+
+def link_agent_files(project_dir: Path) -> list[str]:
+    """Points every tool-specific instructions file at ``AGENTS.md``. Returns
+    the link paths that had to be copied because symlinks aren't available.
+    Existing files are left untouched."""
+    source = project_dir / AGENTS_FILE
+    copied: list[str] = []
+    for link, target in AGENT_LINKS.items():
+        path = project_dir / link
+        if path.exists() or path.is_symlink():
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            os.symlink(target, path)
+        except (OSError, NotImplementedError):
+            shutil.copyfile(source, path)
+            copied.append(link)
+    return copied

{austial_cli-0.1.5 → austial_cli-0.2.0}/src/austial/cli/generators/new_project.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import subprocess
 from pathlib import Path
 
+from austial.cli.generators.agent_files import link_agent_files
 from austial.cli.generators.base import render, write_file
 from austial.cli.naming import to_kebab_case
 
@@ -16,10 +17,16 @@ def create_new_project(
     austial_source_path: str | None = None,
     skip_install: bool = False,
     skip_git: bool = False,
+    skip_agents: bool = False,
 ) -> Path:
     project_dir = (directory or Path.cwd() / name).resolve()
     project_slug = to_kebab_case(name)
-    ctx = {"project_name": name, "project_slug": project_slug, "austial_source_path": austial_source_path}
+    ctx = {
+        "project_name": name,
+        "project_slug": project_slug,
+        "austial_source_path": austial_source_path,
+        "agents": not skip_agents,
+    }
 
     write_file(project_dir / "pyproject.toml", render("project/pyproject.toml.j2", **ctx))
     write_file(project_dir / "README.md", render("project/readme.j2", **ctx))
@@ -27,6 +34,10 @@ def create_new_project(
     write_file(project_dir / ".gitignore", render("project/gitignore.j2", **ctx))
     write_file(project_dir / ".pre-commit-config.yaml", render("project/pre_commit_config.yaml.j2", **ctx))
 
+    if not skip_agents:
+        write_file(project_dir / "AGENTS.md", render("project/agents_md.j2", **ctx))
+        link_agent_files(project_dir)
+
     write_file(project_dir / "src" / "__init__.py", "")
     write_file(project_dir / "src" / "main.py", render("project/main.py.j2", **ctx))
     write_file(project_dir / "src" / "app_module.py", render("project/app_module.py.j2", **ctx))

{austial_cli-0.1.5 → austial_cli-0.2.0}/src/austial/cli/main.py

@@ -46,6 +46,11 @@ def new_project(
     directory: str | None = typer.Option(None, "--directory", "-d", help="Target directory (defaults to ./<name>)."),
     skip_install: bool = typer.Option(False, "--skip-install", help="Don't run `uv sync` after scaffolding."),
     skip_git: bool = typer.Option(False, "--skip-git", help="Don't run `git init` after scaffolding."),
+    skip_agents: bool = typer.Option(
+        False,
+        "--skip-agents",
+        help="Don't write AGENTS.md or the per-tool symlinks (CLAUDE.md, GEMINI.md, ...).",
+    ),
     link: str | None = typer.Option(
         None,
         "--link",
@@ -62,6 +67,7 @@ def new_project(
         austial_source_path=link,
         skip_install=skip_install,
         skip_git=skip_git,
+        skip_agents=skip_agents,
     )
     console.print(f"[bold green]\u2714[/bold green] Project created at [bold]{project_dir}[/bold]")
     console.print("\nNext steps:")

austial_cli-0.2.0/src/austial/cli/templates/project/agents_md.j2

@@ -0,0 +1,162 @@
+# AGENTS.md
+
+This is an **Austial** application: a NestJS-style, batteries-included web
+framework for Python, built on FastAPI. Austial is not FastAPI, Django, or
+NestJS. It looks like all three, and guessing from them produces code that
+does not run. When you are unsure of an API, read the docs instead of
+inventing one:
+
+- Docs: https://docs.austial.com
+- Whole doc set as one file for LLMs: https://docs.austial.com/llms-full.txt
+- Page index: https://docs.austial.com/llms.txt
+
+## Project facts (fill these in)
+
+- App name / purpose: {{ project_name }} -- <what this service does>
+- Database: <postgres | sqlite> via `austial.orm`
+- Auth: <JWT via austial.auth | API key | none>
+- Multi-tenant: <yes | no>
+- Deployed as: <uvicorn src.main:app on ... >
+
+## Commands
+
+```bash
+uv sync --extra dev          # install, including dev tools
+cp .env.example .env         # first time only
+uv run austial serve         # dev server on :8000 with reload
+uv run austial g resource <name>   # scaffold a full CRUD feature module
+uv run ruff check . --fix && uv run ruff format .
+uv run mypy src tests
+uv run pytest -q
+```
+
+**Definition of done:** `ruff check`, `ruff format --check`, `mypy src tests`
+and `pytest` all pass. Never report work as finished without running them.
+
+## Layout
+
+```
+src/
+├── main.py              # AustialFactory.create(AppModule) + global pipes/filters
+├── app_module.py        # root @Module: imports every feature module
+└── modules/<snake_name>/
+    ├── <name>_module.py
+    ├── <name>_controller.py
+    ├── <name>_service.py
+    ├── entities/<name>_entity.py
+    └── dto/create_<name>_dto.py, update_<name>_dto.py
+tests/unit/, tests/e2e/      # files named *_spec.py
+```
+
+- One folder per feature. File names use underscore suffixes
+  (`cats_controller.py`), never dots.
+- Imports are absolute from the project root: `from src.modules.cats...`.
+- Prefer `uv run austial g resource <name>` over hand-writing a feature. It
+  also patches `app_module.py`.
+
+## The mental model
+
+Request pipeline, in order: **guards -> pipes -> interceptors -> handler ->
+exception filters**. Middleware runs before all of it.
+
+1. **Everything must be registered.** A controller goes in a module's
+   `controllers=[...]`, a provider in `providers=[...]`, and the module in
+   an `imports=[...]` chain that reaches `AppModule`. A missing registration
+   shows up as a missing route or a DI error, not an import error.
+2. **Dependency injection is by `__init__` type hint.** Providers are
+   singletons (`Scope.DEFAULT`) unless marked `Scope.TRANSIENT`. There is no
+   request scope. Never instantiate a service yourself with `Foo()`.
+3. **Repositories** are injected as
+   `repo: Repository[Cat] = InjectRepository(Cat)`, and the owning module
+   needs `OrmModule.for_feature([Cat])`. The root needs one
+   `OrmModule.for_root(...)`.
+4. **Request data** uses marker defaults: `Body()`, `Param()`, `Query()`,
+   `Headers()`. DTOs are plain pydantic `BaseModel`s. Route paths use `:id`
+   and `:key*` (catch-all that also matches `/`), not `{id}`.
+5. **Errors:** raise Austial exceptions (`NotFoundException`,
+   `BadRequestException`, `ConflictException`, ...). Do not hand-build error
+   responses. The global `AllExceptionsFilter` renders
+   `statusCode/message/error/timestamp/path`.
+6. **Guards are the security boundary.** Every non-public route must be
+   covered by `AuthGuard` (and `RolesGuard` / `TenantGuard` where relevant).
+   Mark intentionally open routes with `@Public()`.
+
+## Import map
+
+| You need | Import from |
+|---|---|
+| `Module Controller Injectable Get Post Put Patch Delete Body Param Query Headers UseGuards UseInterceptors UsePipes UseFilters HttpCode Header Scope Global Inject`, all `*Exception` classes, `CanActivate ExecutionContext NestInterceptor NestMiddleware PipeTransform ExceptionFilter Catch ValidationPipe AustialFactory Reflector` | `austial` |
+| `ConfigModule ConfigService` | `austial.config` |
+| `OrmModule DataSource Entity Column PrimaryGeneratedColumn Repository InjectRepository FindOptions In NotIn IsNull NotNull ManyToOne OneToMany` | `austial.orm` |
+| `AuthModule AuthConfig AuthGuard AuthService CurrentUser Public JwtStrategy Argon2Hasher TotpStrategy` | `austial.auth` |
+| `AuthzModule RolesGuard Roles Permissions AuthorizeObject PermissionService` | `austial.authz` |
+| `TenancyModule TenantGuard TenantContext RequireTenant Tenanted` | `austial.tenancy` |
+| `SecurityModule SecurityConfig RateLimit RateLimitGuard IdempotencyKeyGuard CsrfInterceptor SecureHeadersMiddleware PIIRedactor EnvelopeEncryptor` | `austial.security` |
+| `AuditModule AuditConfig AuditLogService AuditEvent Audited OrmAuditStore` | `austial.audit` |
+| `JobsModule JobsConfig JobQueue Job Cron Worker` | `austial.jobs` |
+| `StorageModule StorageConfig StorageService SignedUrlService` | `austial.storage` |
+| `MigrationsModule MigrationsConfig MigrationRunner` | `austial.migrations` |
+| `I18nModule I18nConfig I18nService LocaleMiddleware` | `austial.i18n` |
+| `HealthCheckService MemoryHealthIndicator DatabaseHealthIndicator` | `austial.terminus` |
+| `Test` (testing module) | `austial.testing` |
+
+If a symbol is not in this table, check
+https://docs.austial.com/llms-full.txt before using it.
+
+## Do
+
+- Write async handlers and services. The ORM is async end to end.
+- Return typed values or DTOs from handlers, and validate input with DTOs.
+- Filter every query on a `Tenanted` entity by `tenant_id`, and set it
+  explicitly on insert from `TenantContext.require()`.
+- Use `repository.insert(...)` when the primary key is assigned by the
+  application (UUIDs). `save()` would issue an UPDATE.
+- Use `IsNull()` / `NotNull()` to filter on NULL. `{"col": None}` compiles to
+  `= NULL` and never matches.
+- Use `append_only=True` entities for audit and ledger data.
+- Write a test for every new route (`austial.testing.Test`, `httpx`
+  `ASGITransport`) and assert error bodies, not just 200s.
+- Add a new Alembic revision for every schema change. Read the generated
+  file before committing it.
+
+## Do not
+
+- Do not use FastAPI `Depends()` for things Austial's DI already provides.
+- Do not import SQLAlchemy in application code, or build SQL with f-strings.
+  Use `Repository`, `FindOptions` and `QueryBuilder` with bound params.
+- Do not log or audit-log PII, tokens or secrets. Pass records through
+  `PIIRedactor` first.
+- Do not edit a migration that has been applied. Add a new one.
+- Do not hardcode secrets. Read them with `ConfigService.get_or_throw(...)`.
+- Do not rely on `synchronize=True` outside local development and tests.
+- Do not ship the in-memory defaults (see below) to production.
+
+## Not production-safe by default
+
+These ship as in-memory or local reference implementations. Replace each with
+a persistent or shared one before running more than one worker or surviving a
+restart:
+
+| Component | Default | Production need |
+|---|---|---|
+| Refresh tokens | `InMemoryRefreshTokenStore` | ORM/Redis-backed `RefreshTokenStore` |
+| Rate limiting | `InMemoryRateLimitStore` | shared store, plus `trusted_proxy_hops` behind a proxy |
+| Idempotency keys | `InMemoryIdempotencyStore` | persistent store |
+| Audit log | `InMemoryAuditStore` | `OrmAuditStore` or a SIEM store |
+| Background jobs | in-memory `JobBackend` (process-local) | persistent `JobBackend` |
+| File storage | `driver="local"` | `driver="s3"` |
+| Schema | `synchronize=True` | Alembic migrations (`austial-migrate`) |
+
+## Production gates
+
+Before calling a feature production-ready, confirm:
+
+1. All checks in "Definition of done" pass.
+2. Secrets come from the environment and `jwt_secret` /
+   `signed_url_secret` are 32+ characters.
+3. `DataSource.initialize()` runs in a `startup` event handler, because
+   `uvicorn src.main:app` never calls `bootstrap()`.
+4. `GET /health` is wired to `DatabaseHealthIndicator`.
+5. Global `ValidationPipe` and `AllExceptionsFilter` are registered, and
+   `AuthGuard` is global or on every non-public controller.
+6. Full checklist: https://docs.austial.com/ai/production

{austial_cli-0.1.5 → austial_cli-0.2.0}/src/austial/cli/templates/project/readme.j2

@@ -66,3 +66,12 @@ uv run pre-commit run --all-files   # run every hook once, on demand
 Once installed, `git commit` runs formatting/linting/type-checks automatically,
 and `git push` also runs the test suite -- mirroring a typical Nest project's
 husky + lint-staged setup.
+{% if agents %}
+
+## AI coding tools
+
+`AGENTS.md` holds the rules every AI tool should follow in this project (commands, layout, framework
+conventions, production gates). `CLAUDE.md`, `GEMINI.md`, `.windsurfrules`, `.clinerules`, `.rules`,
+`CONVENTIONS.md` and `.github/copilot-instructions.md` are symlinks to it, so there is one file to edit.
+Fill in its **Project facts** block first. See https://docs.austial.com/ai/setup.
+{% endif %}

{austial_cli-0.1.5 → austial_cli-0.2.0}/src/austial/cli/templates/resource/controller.py.j2

@@ -13,21 +13,21 @@ class {{ class_name }}Controller:
 
     @Post()
     async def create(self, dto: Create{{ class_name }}Dto = Body()) -> {{ class_name }}:
-        return self.service.create(dto)
+        return await self.service.create(dto)
 
     @Get()
     async def find_all(self) -> list[{{ class_name }}]:
-        return self.service.find_all()
+        return await self.service.find_all()
 
     @Get(":id")
     async def find_one(self, id: int) -> {{ class_name }}:
-        return self.service.find_one(id)
+        return await self.service.find_one(id)
 
     @Patch(":id")
     async def update(self, id: int, dto: Update{{ class_name }}Dto = Body()) -> {{ class_name }}:
-        return self.service.update(id, dto)
+        return await self.service.update(id, dto)
 
     @Delete(":id")
     async def remove(self, id: int) -> dict:
-        self.service.remove(id)
+        await self.service.remove(id)
         return {"deleted": True}

austial_cli-0.2.0/src/austial/cli/templates/resource/entity.py.j2

@@ -0,0 +1,7 @@
+from austial.orm import Column, Entity, PrimaryGeneratedColumn
+
+
+@Entity()
+class {{ class_name }}:
+    id: int = PrimaryGeneratedColumn()
+    name: str = Column()

austial_cli-0.2.0/src/austial/cli/templates/resource/module.py.j2

@@ -0,0 +1,15 @@
+from austial import Module
+from austial.orm import OrmModule
+
+from src.modules.{{ snake_name }}.{{ snake_name }}_controller import {{ class_name }}Controller
+from src.modules.{{ snake_name }}.{{ snake_name }}_service import {{ class_name }}Service
+from src.modules.{{ snake_name }}.entities.{{ snake_name }}_entity import {{ class_name }}
+
+
+@Module(
+    imports=[OrmModule.for_feature([{{ class_name }}])],
+    controllers=[{{ class_name }}Controller],
+    providers=[{{ class_name }}Service],
+)
+class {{ class_name }}Module:
+    pass

austial_cli-0.2.0/src/austial/cli/templates/resource/service.py.j2

@@ -0,0 +1,33 @@
+from austial import Injectable, NotFoundException
+from austial.orm import InjectRepository, Repository
+
+from src.modules.{{ snake_name }}.dto.create_{{ snake_name }}_dto import Create{{ class_name }}Dto
+from src.modules.{{ snake_name }}.dto.update_{{ snake_name }}_dto import Update{{ class_name }}Dto
+from src.modules.{{ snake_name }}.entities.{{ snake_name }}_entity import {{ class_name }}
+
+
+@Injectable()
+class {{ class_name }}Service:
+    def __init__(self, repository: Repository[{{ class_name }}] = InjectRepository({{ class_name }})):
+        self.repository = repository
+
+    async def create(self, dto: Create{{ class_name }}Dto) -> {{ class_name }}:
+        return await self.repository.save({{ class_name }}(**dto.model_dump()))
+
+    async def find_all(self) -> list[{{ class_name }}]:
+        return await self.repository.find()
+
+    async def find_one(self, id: int) -> {{ class_name }}:
+        item = await self.repository.find_one_by({"id": id})
+        if item is None:
+            raise NotFoundException(f"{{ class_name }} #{id} not found")
+        return item
+
+    async def update(self, id: int, dto: Update{{ class_name }}Dto) -> {{ class_name }}:
+        await self.find_one(id)
+        await self.repository.update(id, dto.model_dump(exclude_unset=True))
+        return await self.find_one(id)
+
+    async def remove(self, id: int) -> None:
+        await self.find_one(id)
+        await self.repository.delete(id)

austial_cli-0.2.0/test/new_project_spec.py

@@ -0,0 +1,68 @@
+"""``austial new`` writes one AGENTS.md and points every AI tool's instructions file at it."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from austial.cli.generators import create_new_project
+from austial.cli.generators.agent_files import AGENT_LINKS
+
+
+def _scaffold(tmp_path: Path, **kwargs) -> Path:
+    return create_new_project("my-app", directory=tmp_path / "my-app", skip_install=True, skip_git=True, **kwargs)
+
+
+def test_new_project_writes_agents_md_with_project_name(tmp_path):
+    project = _scaffold(tmp_path)
+
+    text = (project / "AGENTS.md").read_text()
+    assert "my-app -- <what this service does>" in text
+    assert "{{" not in text and "{%" not in text
+
+
+@pytest.mark.skipif(not hasattr(os, "symlink"), reason="platform has no symlink support")
+def test_every_tool_file_is_a_symlink_that_resolves_to_agents_md(tmp_path):
+    project = _scaffold(tmp_path)
+
+    for link in AGENT_LINKS:
+        path = project / link
+        assert path.is_symlink(), link
+        assert path.resolve() == (project / "AGENTS.md").resolve(), link
+        assert path.read_text() == (project / "AGENTS.md").read_text()
+
+
+def test_skip_agents_writes_none_of_them(tmp_path):
+    project = _scaffold(tmp_path, skip_agents=True)
+
+    assert not (project / "AGENTS.md").exists()
+    for link in AGENT_LINKS:
+        assert not (project / link).exists() and not (project / link).is_symlink()
+
+
+def test_falls_back_to_copies_when_symlinks_are_unavailable(tmp_path, monkeypatch):
+    def _no_symlinks(*args, **kwargs):
+        raise OSError("symlinks not permitted")
+
+    monkeypatch.setattr(os, "symlink", _no_symlinks)
+
+    project = _scaffold(tmp_path)
+
+    for link in AGENT_LINKS:
+        path = project / link
+        assert path.is_file() and not path.is_symlink(), link
+        assert path.read_text() == (project / "AGENTS.md").read_text()
+
+
+def test_existing_tool_file_is_left_untouched(tmp_path):
+    from austial.cli.generators.agent_files import link_agent_files
+
+    (tmp_path / "AGENTS.md").write_text("canonical")
+    (tmp_path / "CLAUDE.md").write_text("mine")
+
+    link_agent_files(tmp_path)
+
+    assert (tmp_path / "CLAUDE.md").read_text() == "mine"
+    assert (tmp_path / "GEMINI.md").read_text() == "canonical"

austial_cli-0.1.5/src/austial/cli/templates/resource/entity.py.j2

@@ -1,6 +0,0 @@
-from pydantic import BaseModel
-
-
-class {{ class_name }}(BaseModel):
-    id: int
-    name: str

austial_cli-0.1.5/src/austial/cli/templates/resource/module.py.j2

@@ -1,9 +0,0 @@
-from austial import Module
-
-from src.modules.{{ snake_name }}.{{ snake_name }}_controller import {{ class_name }}Controller
-from src.modules.{{ snake_name }}.{{ snake_name }}_service import {{ class_name }}Service
-
-
-@Module(controllers=[{{ class_name }}Controller], providers=[{{ class_name }}Service])
-class {{ class_name }}Module:
-    pass

austial_cli-0.1.5/src/austial/cli/templates/resource/service.py.j2

@@ -1,39 +0,0 @@
-from austial import Injectable, NotFoundException
-
-from src.modules.{{ snake_name }}.dto.create_{{ snake_name }}_dto import Create{{ class_name }}Dto
-from src.modules.{{ snake_name }}.dto.update_{{ snake_name }}_dto import Update{{ class_name }}Dto
-from src.modules.{{ snake_name }}.entities.{{ snake_name }}_entity import {{ class_name }}
-
-
-@Injectable()
-class {{ class_name }}Service:
-    """In-memory CRUD store -- swap this out for a real repository backed by
-    ``austial.orm`` (SQLAlchemy) whenever you're ready."""
-
-    def __init__(self):
-        self._items: list[{{ class_name }}] = []
-        self._next_id = 1
-
-    def create(self, dto: Create{{ class_name }}Dto) -> {{ class_name }}:
-        item = {{ class_name }}(id=self._next_id, **dto.model_dump())
-        self._next_id += 1
-        self._items.append(item)
-        return item
-
-    def find_all(self) -> list[{{ class_name }}]:
-        return self._items
-
-    def find_one(self, id: int) -> {{ class_name }}:
-        for item in self._items:
-            if item.id == id:
-                return item
-        raise NotFoundException(f"{{ class_name }} #{id} not found")
-
-    def update(self, id: int, dto: Update{{ class_name }}Dto) -> {{ class_name }}:
-        item = self.find_one(id)
-        updated = item.model_copy(update=dto.model_dump(exclude_unset=True))
-        self._items[self._items.index(item)] = updated
-        return updated
-
-    def remove(self, id: int) -> None:
-        self._items.remove(self.find_one(id))