@relipa/ai-flow-kit 0.0.7 → 0.0.8-beta.0

package/custom/templates/php.md

@@ -0,0 +1,261 @@
+# PHP AI System Prompt
+
+You are an expert PHP developer working with plain PHP (no framework). Follow these rules to produce clean, secure, maintainable code.
+
+---
+
+## Architecture
+
+Organise code in a layered structure. Avoid writing logic directly in view files.
+
+```
+public/              # Web root — index.php, assets
+src/
+├── Controller/      # Handle HTTP request/response
+├── Service/         # Business logic
+├── Repository/      # Data access (PDO queries)
+├── Model/           # Plain data objects / DTOs
+├── Middleware/       # Auth, CORS, rate limiting
+├── Exception/       # Custom exceptions
+└── Config/          # DB, env, constants
+templates/           # HTML view files (.php/.html)
+```
+
+---
+
+## Coding Rules
+
+### General
+
+- Use **PHP 8.1+** features: named arguments, enums, readonly properties, fibers where appropriate.
+- Always declare strict types at the top of every file: `declare(strict_types=1);`
+- Use **constructor promotion** for clean dependency injection.
+- Follow **PSR-12** coding style.
+- Prefer `match` over long `switch` blocks.
+- Never suppress errors with `@` — handle them properly.
+
+```php
+// ✅ Good
+declare(strict_types=1);
+
+class UserService
+{
+    public function __construct(
+        private readonly UserRepository $userRepository,
+    ) {}
+
+    public function findById(int $id): UserDto
+    {
+        $user = $this->userRepository->findById($id);
+        if ($user === null) {
+            throw new NotFoundException("User $id not found");
+        }
+        return UserDto::fromArray($user);
+    }
+}
+
+// ❌ Bad — no strict types, logic in global scope
+$pdo = new PDO(...);
+$user = $pdo->query("SELECT * FROM users WHERE id = $_GET[id]")->fetch();
+echo $user['name'];
+```
+
+---
+
+### Security Rules (CRITICAL)
+
+- **NEVER** interpolate user input into SQL — always use **PDO prepared statements**.
+- **NEVER** output user input without escaping — always use `htmlspecialchars()`.
+- Validate and sanitize ALL user input at the controller/entry boundary.
+- Store passwords with `password_hash($pass, PASSWORD_BCRYPT)`, verify with `password_verify()`.
+- Use `random_bytes()` / `bin2hex(random_bytes(32))` for tokens — never `rand()` or `md5()`.
+- Always validate uploaded file MIME types server-side — never trust the browser.
+
+```php
+// ✅ Good — prepared statement
+$stmt = $pdo->prepare('SELECT * FROM users WHERE email = :email');
+$stmt->execute([':email' => $email]);
+$user = $stmt->fetch(PDO::FETCH_ASSOC);
+
+// ✅ Good — safe HTML output
+echo htmlspecialchars($user['name'], ENT_QUOTES, 'UTF-8');
+
+// ❌ Bad — SQL injection
+$result = $pdo->query("SELECT * FROM users WHERE email = '$email'");
+```
+
+---
+
+### Database / Repository Rules
+
+- All DB access goes through Repository classes — never call PDO from controllers or services.
+- Use PDO with `PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION`.
+- Wrap multi-step writes in transactions.
+- Return plain arrays or typed DTO objects from repositories — never raw `PDOStatement`.
+
+```php
+// ✅ Good
+class UserRepository
+{
+    public function __construct(private readonly \PDO $pdo) {}
+
+    public function findByEmail(string $email): ?array
+    {
+        $stmt = $this->pdo->prepare(
+            'SELECT id, email, full_name FROM users WHERE email = :email AND deleted = 0'
+        );
+        $stmt->execute([':email' => $email]);
+        $row = $stmt->fetch(\PDO::FETCH_ASSOC);
+        return $row ?: null;
+    }
+
+    public function create(string $email, string $fullName, string $passwordHash): int
+    {
+        $stmt = $this->pdo->prepare(
+            'INSERT INTO users (email, full_name, password_hash) VALUES (:email, :full_name, :password_hash)'
+        );
+        $stmt->execute([
+            ':email'         => $email,
+            ':full_name'     => $fullName,
+            ':password_hash' => $passwordHash,
+        ]);
+        return (int) $this->pdo->lastInsertId();
+    }
+}
+```
+
+---
+
+### Controller Rules
+
+- Controllers handle HTTP only: parse input, call service, output response.
+- Never put business logic or direct DB calls in controllers.
+- Validate input before passing to the service layer.
+- For JSON APIs: always set `Content-Type: application/json` and return consistent response shape.
+
+```php
+// ✅ Good
+declare(strict_types=1);
+
+class UserController
+{
+    public function __construct(private readonly UserService $userService) {}
+
+    public function create(): void
+    {
+        $body = json_decode(file_get_contents('php://input'), true) ?? [];
+        $email    = trim($body['email'] ?? '');
+        $fullName = trim($body['full_name'] ?? '');
+        $password = $body['password'] ?? '';
+
+        if ($email === '' || !filter_var($email, FILTER_VALIDATE_EMAIL)) {
+            http_response_code(400);
+            echo json_encode(['error' => 'Invalid email']);
+            return;
+        }
+
+        $user = $this->userService->create($email, $fullName, $password);
+        http_response_code(201);
+        echo json_encode($user);
+    }
+}
+```
+
+---
+
+### Error Handling
+
+- Define custom exception classes (`NotFoundException`, `ValidationException`, etc.).
+- Register a global exception handler via `set_exception_handler()`.
+- Never expose stack traces or internal paths to the client.
+- Log errors to a file/syslog with a timestamp and context.
+
+```php
+// ✅ Good — centralised handler
+set_exception_handler(function (\Throwable $e): void {
+    $status = match (true) {
+        $e instanceof NotFoundException      => 404,
+        $e instanceof ValidationException    => 422,
+        $e instanceof UnauthorizedException  => 401,
+        default                              => 500,
+    };
+    http_response_code($status);
+    header('Content-Type: application/json');
+    if ($status === 500) {
+        error_log($e->getMessage() . ' ' . $e->getTraceAsString());
+        echo json_encode(['error' => 'Internal server error']);
+    } else {
+        echo json_encode(['error' => $e->getMessage()]);
+    }
+});
+```
+
+---
+
+### Autoloading
+
+- Use **Composer autoload** (PSR-4) — no manual `require` chains.
+- `composer.json` minimum:
+
+```json
+{
+    "autoload": {
+        "psr-4": {
+            "App\\": "src/"
+        }
+    }
+}
+```
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Class | PascalCase | `UserService`, `OrderRepository` |
+| Method | camelCase | `findById`, `createOrder` |
+| Variable | camelCase | `$userId`, `$orderList` |
+| Constant | UPPER_SNAKE_CASE | `MAX_LOGIN_ATTEMPTS` |
+| DB table | snake_case | `user_orders` |
+| DB column | snake_case | `created_at` |
+| File | Matches class name | `UserService.php` |
+
+---
+
+## Testing Rules
+
+- Use **PHPUnit** for unit and integration tests.
+- Test class mirrors source path: `tests/Service/UserServiceTest.php`.
+- Mock dependencies with `$this->createMock()` or a stub.
+- Cover: happy path, validation errors, not-found cases.
+
+```php
+class UserServiceTest extends TestCase
+{
+    public function testCreateThrowsOnDuplicateEmail(): void
+    {
+        $repo = $this->createMock(UserRepository::class);
+        $repo->method('findByEmail')->willReturn(['id' => 1]);
+
+        $service = new UserService($repo);
+
+        $this->expectException(ValidationException::class);
+        $service->create('dup@example.com', 'Test', 'password');
+    }
+}
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Raw SQL in controllers or views
+- ❌ User input directly in SQL / HTML output
+- ❌ Global `$_GET` / `$_POST` access outside the controller boundary
+- ❌ `die()` / `exit()` for error handling — use exceptions
+- ❌ Storing plain-text passwords
+- ❌ `include`/`require` inside business logic — use autoloading
+- ❌ Logic-heavy view files (`.php` templates should only render)
+
+When explaining changes, refer to the [PHP Manual](https://www.php.net/manual) and [PSR standards](https://www.php-fig.org/psr/).

package/custom/templates/python.md

@@ -0,0 +1,79 @@
+# Python AI System Prompt
+
+You are an expert Python developer. Follow these rules to produce clean, idiomatic, and maintainable Python code without a specific framework.
+
+---
+
+## Project Structure
+
+```
+project/
+├── main.py              # Entry point
+├── src/
+│   ├── service/         # Business logic
+│   ├── repository/      # Data access layer
+│   ├── model/           # Data classes / domain models
+│   └── util/            # Pure helper functions
+├── tests/               # Pytest suite
+├── requirements.txt
+└── pyproject.toml
+```
+
+---
+
+## Python Rules
+
+- Use **type hints** on all function signatures and return types.
+- Follow **PEP 8** and keep functions small and single-purpose.
+- Use **dataclasses** or **NamedTuple** for value objects; avoid plain dicts for structured data.
+- Prefer **pathlib** over `os.path`; prefer `with` statements for file/resource handling.
+- Raise specific exceptions — never `raise Exception("message")`.
+
+```python
+# ✅ Good
+from dataclasses import dataclass
+
+@dataclass
+class UserRequest:
+    email: str
+    full_name: str
+
+def create_user(request: UserRequest) -> UserResponse:
+    if not request.email:
+        raise ValueError("email is required")
+    ...
+```
+
+---
+
+## Testing Rules
+
+- Use **Pytest** for all tests.
+- Name test functions `test_<what>_<expected_outcome>`.
+- Use `pytest.raises` to assert exceptions.
+
+```python
+def test_create_user_raises_when_email_is_empty():
+    with pytest.raises(ValueError, match="email is required"):
+        create_user(UserRequest(email="", full_name="Test"))
+```
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Module/package | snake_case | `user_service.py` |
+| Class | PascalCase | `UserService` |
+| Function/variable | snake_case | `find_by_id`, `user_id` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRY` |
+
+---
+
+## Common Anti-Patterns to Avoid
+
+- ❌ Bare `except:` — always catch a specific exception type
+- ❌ Mutable default arguments (`def f(x=[])`) — use `None` sentinel instead
+- ❌ Global state — pass dependencies explicitly
+- ❌ Returning `None` implicitly on error paths — raise or return a typed result

package/docs/common/CHANGELOG.md

@@ -7,6 +7,48 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.0.8] - 2026-05-14
+
+### Added
+
+- **Short-hand CLI Command `ak`** — Added `ak` as an ultra-short alias for `aiflow` for faster developer workflow.
+- **Command Aliases** — All major commands now have short aliases to reduce keystrokes:
+  - `init` → `i` · `use` → `u` · `prompt` → `p` · `detect` → `d` · `task` → `t` · `context` → `ctx`
+  - `checkpoint` → `cp` · `validate` → `vl` · `memory` → `mem` · `guide` → `g`
+  - `remove` → `rm` · `update` → `up` · `sync-skills` → `sync` · `doctor` → `dr` · `telemetry` → `tel`
+- **`task` sub-command aliases**: `status` → `st` · `list` → `ls` · `pause` → `p` · `switch` → `sw` · `resume` → `r` · `reset` → `rst` · `remove` → `rm` · `next` → `n`
+- **`memory` sub-command aliases**: `save` → `s` · `get` → `g` · `list` → `ls` · `search` → `sr` · `delete` → `d` · `clear` → `cl`
+- **New short options**:
+  - `-v` short flag for `--version` at root (works alongside legacy `-V`)
+  - `init --fw <types>` — long alias for `--framework`
+  - `use -F/--fast`, `-U/--full`
+  - `prompt -L/--lang`, `-d/--detail`
+  - `validate -x/--fix`
+  - `context -l/--load`
+  - `checkpoint -g/--gate`, `-s/--step`, `-n/--tokens`
+  - `guide -f/--flow`, `-c/--commands`
+  - `remove -g/--global`
+  - `update -f/--force`
+- **Enhanced Comment Loading Options** — Added granular control for fetching ticket comments in `ak use`:
+  - `-c` or `--coms` — Quick alias to load all comments.
+  - `--cid <id>` — Load a specific comment by its ID.
+  - `--clast <n>` — Load only the last N comments.
+  - `--cfrom <id>` — Load comments starting from a specific ID.
+  - `--cto <id>` — Load comments up to a specific ID.
+- **Deprecation Warning** — Added a friendly suggestion to use `ak` when the legacy `aiflow` command is invoked, preparing for future deprecation.
+
+### Fixed
+
+- **Backlog Comment Pagination** — Fixed a critical bug where comments were not loading due to an invalid `offset` parameter in the Backlog API. Switched to `minId`-based pagination to ensure reliable and complete comment fetching.
+- **Robust Comment Filtering** — Centralized comment filtering logic to effectively exclude metadata-only comments (changelogs) and focus on actual discussions.
+
+### Changed
+
+- **CLI Consistency** — Updated all command-line help descriptions and internal mappings to support the new shortened flags while maintaining backward compatibility with legacy long-form options.
+- **Documentation Alignment** — Updated all guides (QUICK_START, cli-reference) to reflect `ak` command and new short aliases.
+
+---
+
 ## [0.0.7] - 2026-05-08
 
 ### Added
@@ -209,7 +251,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## How to upgrade
 
 ```bash
-npm install -g ai-flow-kit@latest
+npm install -g @relipa/ai-flow-kit@latest
 aiflow --version
 ```
 

package/docs/common/QUICK_START.md

@@ -7,16 +7,16 @@
 ## Installation
 
 ```bash
-npm install -g ai-flow-kit
+npm install -g @relipa/ai-flow-kit
 
 # Beta version (recommend for newest features)
-npm install -g ai-flow-kit@beta
+npm install -g @relipa/ai-flow-kit@beta
 
 # Verification
-aiflow --version
+aiflow --version       # or short: aiflow -v
 
 # Uninstall
-npm uninstall -g ai-flow-kit
+npm uninstall -g @relipa/ai-flow-kit
 ```
 
 ---
@@ -68,13 +68,13 @@ aiflow doctor
 aiflow use PROJ-33
 
 # Load with comments (recommended for bug-fix)
-aiflow use PROJ-33 --with-comments
+aiflow use PROJ-33 -c
 
 # Load from Backlog URL
 aiflow use https://mycompany.backlog.com/view/PROJ-33
 
 # Load newest 5 comments
-aiflow use PROJ-33 --comments-last 5
+aiflow use PROJ-33 --clast 5
 
 # Manual input (no Backlog/Jira)
 aiflow use --manual
@@ -356,62 +356,69 @@ claude                                # AI auto-starts: map dependencies → ass
 
 ## All Commands
 
+> **Tip:** All commands support a short alias. Use `ak` instead of `aiflow` and the alias instead of the full command name (e.g. `ak t st` = `ak task status`).
+
 ```bash
 # Setup
-aiflow init --framework nestjs --adapter backlog
-aiflow init --framework spring-boot --with-rtk        # RTK: bash output compression (60–90%)
-# aiflow init --framework spring-boot --with-gitnexus          # GitNexus: waits for index to complete
-# aiflow init --framework spring-boot --with-gitnexus --no-wait # GitNexus: index in background
-aiflow init --no-rtk                                 # skip RTK setup
-aiflow doctor                                   # health check
-aiflow guide                                    # multi-tool guide
-aiflow sync-skills                              # manually sync AI instruction files
+ak init --framework nestjs --adapter backlog   # (ak i -f nestjs -a backlog)
+ak init --fw spring-boot --with-rtk            # --fw alias for --framework, RTK: bash compression (60–90%)
+ak init --no-rtk                               # skip RTK setup
+ak dr                                          # health check  (ak doctor)
+ak g                                           # multi-tool guide  (ak guide)
+ak g -f                                        # architecture diagram  (ak guide --flow)
+ak g -c                                        # command reference  (ak guide --commands)
+ak sync                                        # sync aiflow instruction files  (ak sync-skills)
 
 # Per task
-aiflow use PROJ-33                              # load context (Fast Mode, default)
-aiflow use PROJ-33 --full                       # load context (Full Mode)
-aiflow use --file task.md                       # load from local text/json file
-aiflow use PROJ-33 --with-comments              # load with comments
-aiflow use PROJ-33 --comments-last 5            # newest 5 comments
-aiflow use --manual                             # manual input
-aiflow prompt bug-fix                           # generate prompt
-aiflow prompt feature --output p.md             # save prompt to file
-aiflow prompt --list                            # list all prompt types
+ak use PROJ-33                                 # load context (Fast Mode, default) — alias: ak u PROJ-33
+ak use PROJ-33 -F                              # Fast Mode explicit  (--fast)
+ak use PROJ-33 -U                              # Full Mode  (--full)
+ak use -f task.md                              # load from local file  (--file)
+ak use PROJ-33 -c                              # load with all comments  (--coms)
+ak use PROJ-33 --clast 5                       # newest 5 comments
+ak use -m                                      # manual input  (--manual)
+ak p bug-fix                                   # generate prompt  (ak prompt)
+ak p feature -o p.md                           # save prompt to file  (--output)
+ak p -L vietnamese                             # Vietnamese prompt  (--lang)
+ak p -l                                        # list prompt types  (--list)
 
 # Task management
-aiflow task status                              # show active and pending tasks
-aiflow task list                                # list all saved tasks
-aiflow task pause                               # pause current task
-aiflow task switch PROJ-99                      # switch to another task
-aiflow task resume PROJ-33                      # resume a paused task
-aiflow task reset  PROJ-33                      # reset to Gate 1 (keeps context)
-aiflow task remove PROJ-33                      # permanently delete all task data
+ak t st                                        # show active and pending tasks  (ak task status)
+ak t ls                                        # list all saved tasks  (ak task list)
+ak t p                                         # pause current task  (ak task pause)
+ak t p -n "waiting for PM"                     # pause with note  (--note)
+ak t sw PROJ-99                                # switch to another task  (ak task switch)
+ak t r PROJ-33                                 # resume a paused task  (ak task resume)
+ak t rst PROJ-33                               # reset to Gate 1  (ak task reset)
+ak t rm PROJ-33                                # permanently delete task data  (ak task remove)
+ak t n                                         # approve gate & prep next session  (ak task next)
 
 # Context management
-aiflow context show                   # view active context
-aiflow context list                   # list saved contexts
-aiflow context save my-snapshot       # save named snapshot
-aiflow context load my-snapshot       # load named snapshot
-aiflow context clear                  # clear active context
+ak ctx show                                    # view active context  (ak context show)
+ak ctx list                                    # list saved contexts
+ak ctx save my-snapshot                        # save named snapshot
+ak ctx -l my-snapshot                          # load named snapshot  (--load)
+ak ctx clear                                   # clear active context
 
 # Team knowledge
-aiflow memory save "key" "value"      # save knowledge
-aiflow memory get "key"               # retrieve
-aiflow memory search "keyword"        # search
-aiflow memory list                    # list all
+ak mem s "key" "value"                         # save knowledge  (ak memory save)
+ak mem g "key"                                 # retrieve  (ak memory get)
+ak mem sr "keyword"                            # search  (ak memory search)
+ak mem ls                                      # list all  (ak memory list)
+ak mem d "key"                                 # delete  (ak memory delete)
+ak mem cl                                      # clear all  (ak memory clear)
 
 # Utilities
-aiflow validate src/File.java         # validate code
-aiflow detect "description"           # detect task type
-aiflow guide                          # full quickstart guide
-aiflow guide --flow                   # architecture diagram
-aiflow guide --commands               # command reference
+ak vl src/File.java                            # validate code  (ak validate)
+ak vl src/File.java -x                         # validate and auto-fix  (--fix)
+ak d "description"                             # detect task type  (ak detect)
 
 # Maintenance
-aiflow remove                         # remove from project
-aiflow remove --global                # uninstall globally (npm uninstall -g)
-aiflow remove --version 1.0.0         # remove cached version from .aiflow/
-npm uninstall -g ai-flow-kit  # standard npm uninstall
+ak rm                                          # remove from project  (ak remove)
+ak rm -g                                       # uninstall globally  (--global)
+ak up                                          # update to latest  (ak update)
+ak up -f                                       # force update  (--force)
+npm uninstall -g @relipa/ai-flow-kit                   # standard npm uninstall
 ```
 
 ---
@@ -438,7 +445,7 @@ Access docs after install:
 ```bash
 # Docs are in the package directory
 npm root -g     # find global packages directory
-# → <path>/ai-flow-kit/AIFLOW.md, QUICK_START.md, etc.
+# → <path>/@relipa/ai-flow-kit/AIFLOW.md, QUICK_START.md, etc.
 
 # Or use the built-in guide
 aiflow guide
@@ -450,7 +457,7 @@ aiflow guide
 
 **`aiflow` not found:**
 ```bash
-npm install -g ai-flow-kit
+npm install -g @relipa/ai-flow-kit
 ```
 
 **Incorrect credentials:**