actdim-along 4.9.0__tar.gz

actdim_along-4.9.0/.along/.migration-backup/2026-11-14-230651/.along/rules/gates.yaml

@@ -0,0 +1,21 @@
+# Repository overrides of the built-in gate catalogue (alongkit/hooks/default_gates.yaml).
+# Repo-owned: `along rules attach` never rewrites this file.
+version: 1
+
+gates:
+  # AGENTS.md requires an approved plan before source edits and a test run before a turn
+  # ends; hold sessions to that even before they are bound to an issue.
+  - id: require_plan_approval
+    enforce_unbound: true
+
+  # The suite tests Markdown too (protocol and AGENTS.md budgets, skill manifests), so a
+  # documentation edit needs a test run here as well.
+  - id: test_before_stop
+    enforce_unbound: true
+    count_docs: true
+    doc_tests:
+      - test_context_budget.py
+      - test_sanitizer.py
+      - test_kb_sync.py
+      - test_kb_search.py
+      - test_skills_and_scripts.py

actdim_along-4.9.0/.along/.migration-backup/2026-11-14-230651/.along/rules/languages/python.md

@@ -0,0 +1,132 @@
+<!-- managed by along: do not edit. Project guidelines belong in docs/ and AGENTS.md -->
+<!-- template: languages/python.md sha256:99c9bbb4ad79fbe6f594e3932cb762e5d6889e14c4c12cf81546c6f8ed016d77 -->
+
+# Python Coding Standards & Best Practices
+
+Modern Python 3.11+ engineering conventions based on PEP 8, Google Python Style Guide, UV workspaces, and strict static type analysis.
+
+---
+
+## 1. Monorepos & Workspace Management with UV
+
+- **UV Workspaces Standard**:
+  - For multi-package or microservice repositories, use `uv` workspaces to orchestrate dependencies centrally in root `pyproject.toml`.
+  - Declare workspace members under `[tool.uv.workspace]`. Sub-packages reference sibling packages using editable path dependencies (`{ workspace = true }`).
+
+```toml
+# pyproject.toml (root)
+[tool.uv.workspace]
+members = ["packages/*", "services/*"]
+```
+
+---
+
+## 2. Static Type Annotations
+
+- **Strict Typing**: Type annotate all function arguments and return types. Avoid `Any` where possible.
+- **Modern Syntax**: Use Python 3.10+ union syntax (`X | Y` instead of `Union[X, Y]`, `list[str]` instead of `List[str]`).
+- **Type Checking**: Ensure code passes `mypy --strict` or `pyright` without errors.
+
+```python
+# Recommended: Modern type hints and dataclass
+from dataclasses import dataclass
+from typing import Self
+
+@dataclass(frozen=True, slots=True)
+class Coordinate:
+    x: float
+    y: float
+
+    @classmethod
+    def from_tuple(cls, val: tuple[float, float]) -> Self:
+        return cls(x=val[0], y=val[1])
+```
+
+---
+
+## 3. Data Structures & Immutability
+
+- **Dataclasses & Pydantic**: Use `@dataclass(frozen=True, slots=True)` for internal value objects and Pydantic `BaseModel` for external API validation.
+- **Generators & Iterators**: Use generator expressions (`(x for x in data)`) instead of eager list comprehensions for memory-efficient iteration over large streams.
+- **Context Managers**: Always manage I/O resources using `with` statements (`with open(...) as f:`).
+
+---
+
+## 4. Formatting & Linting Tooling
+
+- **Ruff & Black**: Use Ruff for ultra-fast linting and Black/Ruff-format for deterministic code formatting.
+- **Line Length**: Target standard 88 or 100 character line limits.
+- **Naming Conventions**:
+  - `snake_case`: Variables, functions, methods, modules.
+  - `PascalCase`: Classes, Exceptions, Pydantic models.
+  - `UPPER_SNAKE_CASE`: Constants.
+
+---
+
+## 5. Error Handling & Exceptions
+
+- **Specific Exceptions**: Never catch bare `except:`. Catch specific exceptions (`except (ValueError, KeyError) as e:`).
+- **Custom Exceptions**: Derive domain errors from a custom base exception class (`class DomainError(Exception): pass`).
+- **Exception Chaining**: Use `raise NewException(...) from original_err` to preserve stack traces.
+
+---
+
+## 6. Packaging & Distributing AI Documentation (LLM-Wiki)
+
+- **Standard PEP 621 `pyproject.toml` & Package Data**:
+  - When publishing Python packages to PyPI or internal registries, configure the build backend to bundle `AGENTS.md`, `llms.txt`, and the `docs/` folder into wheels (`.whl`) and source distributions (`.tar.gz`).
+
+```toml
+# pyproject.toml (Hatchling / Standard PEP 621)
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "myorg-core"
+version = "1.0.0"
+readme = "README.md"
+keywords = ["along", "ai-agent", "llms", "rules"]
+
+[tool.hatch.build.targets.wheel.shared-data]
+"AGENTS.md" = "myorg_core/AGENTS.md"
+"llms.txt" = "myorg_core/llms.txt"
+"docs" = "myorg_core/docs"
+```
+
+- **Setuptools & `MANIFEST.in` (Standard / Vanilla Tooling)**:
+  - When using standard `setuptools`, ensure non-code AI files are included in source distributions and wheels:
+
+```ini
+# MANIFEST.in
+include README.md
+include AGENTS.md
+include llms.txt
+recursive-include docs *.md
+```
+
+```toml
+# pyproject.toml (Setuptools)
+[tool.setuptools.package-data]
+"myorg_core" = ["AGENTS.md", "llms.txt", "docs/**/*.md"]
+```
+
+- **Poetry / Flit (Recommended Alternatives)**:
+  - With Poetry or Flit, declare explicit inclusions in `pyproject.toml`:
+
+```toml
+# pyproject.toml (Poetry)
+[tool.poetry]
+name = "myorg-core"
+include = [
+    { path = "AGENTS.md" },
+    { path = "llms.txt" },
+    { path = "docs" }
+]
+```
+
+- **Consumer & Upward Discovery Protocol**:
+  - When downstream projects install the dependency via `pip install`, `uv add`, or `requirements.txt`, files are installed into `.venv/lib/site-packages/<package>/`.
+  - The Along dependency scanner (`along-dep-scan`) inspects `pyproject.toml` / `requirements.txt`, resolves the installed package directory in the active virtual environment, detects `AGENTS.md` and `docs/`, and registers them into `docs/topic--dependencies.md`.
+
+

actdim_along-4.9.0/.along/.migration-backup/2026-11-14-230651/.along/rules/languages/typescript.md

@@ -0,0 +1,122 @@
+<!-- managed by along: do not edit. Project guidelines belong in docs/ and AGENTS.md -->
+<!-- template: languages/typescript.md sha256:1ee034239cddda035a603f2f0cd17615b61a96ddfdb54047bc1ff42b8826f44d -->
+
+# TypeScript Coding Standards & Best Practices
+
+Strict TypeScript conventions for production-grade, maintainable codebases and monorepos.
+
+---
+
+## 1. Monorepos & Workspace Dependency Management
+
+- **PNPM Workspaces Standard**:
+  - In multi-package or multi-platform repositories, use PNPM workspaces (`pnpm-workspace.yaml`) to manage dependencies across packages.
+  - Link internal repository packages using the `workspace:*` protocol (e.g. `"@myorg/core": "workspace:*"`). `pnpm publish` automatically resolves and replaces `workspace:*` with exact semver versions when publishing to a registry.
+  - Use PNPM Catalogs (`pnpm:catalog:`) in the root `pnpm-workspace.yaml` to enforce uniform external dependency versions (React, TypeScript, Vitest, MSW) across all workspace members without version drift.
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - "packages/*"
+  - "apps/*"
+
+catalog:
+  typescript: ^5.5.0
+  vitest: ^2.0.0
+  msw: ^2.4.0
+```
+
+---
+
+## 2. Strict Typing & Zero `any`
+
+- **Compiler Configuration**: Enforce `"strict": true`, `"noImplicitAny": true`, `"strictNullChecks": true`, `"noUncheckedIndexedAccess": true`.
+- **Ban `any`**: Never use `any`. Use `unknown` when the type is truly dynamic, and narrow it using type guards (`typeof`, `instanceof`, custom type predicates).
+- **Explicit Return Types**: All exported functions and API boundaries must declare explicit return types.
+
+```typescript
+// Recommended: Type guard with unknown
+function isApiResponse(data: unknown): data is { success: boolean; data: string } {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    "success" in data &&
+    typeof (data as Record<string, unknown>).success === "boolean"
+  );
+}
+```
+
+---
+
+## 3. Types vs Interfaces & Data Modeling
+
+- **Interfaces for Object Shapes & Extension**: Use `interface` for object contracts, classes, and public APIs that may be augmented.
+- **Type Aliases for Unions & Utilities**: Use `type` for unions, intersections, primitives, tuples, and mapped types.
+- **Discriminated Unions**: Model domain states using discriminated unions with a common literal discriminator field (e.g. `type` or `status`).
+
+```typescript
+// Recommended: Discriminated union
+type AsyncResult<T> =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "success"; data: T }
+  | { status: "error"; error: Error };
+```
+
+---
+
+## 4. Immutability & Modern Conventions
+
+- **Readonly Collections**: Prefer `ReadonlyArray<T>` or `readonly T[]` and `as const` assertions for immutable configuration and lookup tables.
+- **Optional Chaining & Nullish Coalescing**: Prefer `?.` and `??` over verbose logical checks (`&&` or `||`).
+- **Exact Optional Properties**: Explicitly distinguish between `undefined` and missing properties.
+
+---
+
+## 5. Naming & File Organization
+
+- **PascalCase**: Classes, Interfaces, Types, Enums, React Components.
+- **camelCase**: Variables, functions, methods, properties.
+- **UPPER_SNAKE_CASE**: Global constants.
+- **kebab-case**: Source filenames (e.g. `user-service.ts`, `auth-guard.ts`).
+
+---
+
+## 6. Package Distribution & AI Metadata (LLM-Wiki)
+
+- **Explicit `package.json` `"files"` Whitelist (Standard / Vanilla)**:
+  - Avoid relying on `.npmignore` alone. Always explicitly declare the `"files"` array in `package.json` to guarantee that compiled output (`dist`), AI rules (`AGENTS.md`, `llms.txt`), and the `docs/` Wiki are published in npm packages.
+
+```json
+{
+  "name": "@myorg/core",
+  "version": "1.0.0",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "llms.txt",
+    "docs",
+    "README.md"
+  ],
+  "keywords": ["along", "ai-agent", "llms", "rules"],
+  "ai": {
+    "agents": "AGENTS.md",
+    "llms": "llms.txt",
+    "wiki": "docs"
+  }
+}
+```
+
+- **PNPM Workspaces & Monorepo Publishing (Recommended)**:
+  - Use `pnpm publish --filter <package>` to publish individual workspace packages.
+  - The `workspace:*` protocol automatically translates to exact semantic versions during `pnpm publish`.
+  - Place shared root documentation in `docs/` and package-specific architectural articles in `packages/<pkg>/docs/`.
+
+- **Consumer & Upward Discovery Protocol**:
+  - When consumers install the package (`pnpm add @myorg/core`, `npm i @myorg/core`), package files reside in `node_modules/@myorg/core/`.
+  - Along dependency scanner (`along-dep-scan`) inspects `package.json` dependencies, resolves the package in `node_modules/`, identifies `AGENTS.md` and `docs/` (or manifest `"ai"` metadata), and records links in `docs/topic--dependencies.md`.
+
+

actdim_along-4.9.0/.along/.migration-backup/2026-11-14-230651/.along/rules/platforms/web.md

@@ -0,0 +1,59 @@
+<!-- managed by along: do not edit. Project guidelines belong in docs/ and AGENTS.md -->
+<!-- template: platforms/web.md sha256:71bfed6b4ef6fdba63dc3faf510edd4c380f7ed5f51f48ad51b3ab072cad9985 -->
+
+# Web Application Engineering Guidelines & Best Practices
+
+Strict architectural and engineering standards for browser-based and SSR web applications.
+
+---
+
+## 1. Network & API Layer Architecture
+
+1. **Mock Service Worker (MSW) Standard for REST API Simulation**:
+   - Use MSW (`msw`) as the standard for REST API mocking and network interception.
+   - **Offline / Serverless Development**: MSW is strongly recommended to allow frontend and UI teams to build, iterate, and test client application logic completely decoupled from a running backend server.
+   - **Zero Monkey-Patching**: Do not monkey-patch `window.fetch` or `axios` manually; intercept network traffic at the Service Worker layer in the browser (`setupWorker`) or the native request interceptor layer in Node / Vitest (`setupServer`).
+   - **Handler Colocation**: Colocate request handlers by domain or entity in `src/mocks/handlers/` (e.g. `handlers/auth.ts`, `handlers/orders.ts`).
+   - **Schema Parity**: Maintain strict schema parity between production OpenAPI/TypeScript API contracts and MSW mock response payloads.
+
+2. **Client-Server State Separation**:
+   - Separate Server State (cached API data, query status) from Client State (UI toggles, transient form inputs, modal visibility).
+   - Use dedicated cache management (e.g. TanStack Query, SWR, or RTK Query) rather than storing remote API responses in global UI stores (such as Zustand, Redux, or Pinia).
+
+3. **Defensive Network Boundaries**:
+   - Validate incoming API payloads at the boundary using schema parsers (e.g. Zod, ArkType, Valibot) before data enters application state.
+   - Explicitly handle all 4xx/5xx HTTP statuses and network timeout failures with typed error states.
+
+---
+
+## 2. Rendering, Hydration & Lifecycle
+
+1. **SSR / Client Hydration Safety**:
+   - Never access browser globals (`window`, `document`, `localStorage`, `sessionStorage`) during initial render or module evaluation in SSR contexts.
+   - Guard client-only logic inside lifecycle hooks (`useEffect`, `onMounted`) or explicit environment checks (`typeof window !== "undefined"`).
+
+2. **Bundle Boundaries & Code Splitting**:
+   - Lazy-load heavy non-critical views (routes, administration dashboards, rich text editors, charts) via dynamic imports.
+   - Keep common dependency vendors tree-shakeable. Avoid importing monolithic libraries when modular subpath imports are available.
+
+---
+
+## 3. UI Accessibility (A11y) & UX Invariants
+
+1. **Semantic HTML**:
+   - Prefer native HTML interactive elements (`<button>`, `<a>`, `<input>`, `<dialog>`) over `div` or `span` with custom click handlers.
+   - For custom interactive controls, supply standard ARIA attributes (`role`, `aria-expanded`, `aria-controls`, `aria-label`).
+
+2. **Keyboard Navigation & Focus Management**:
+   - Ensure all interactive elements have visible focus states (`:focus-visible`) and are keyboard-reachable (`Tab`, `Enter`, `Escape` for modals).
+   - Trap focus inside active modal dialogs and restore focus to trigger elements upon dismissal.
+
+---
+
+## 4. Local Storage & Offline Resilience
+
+1. **Storage Sandboxing**:
+   - Wrap `localStorage` / `sessionStorage` in type-safe adapters with fallback mechanisms (e.g. in-memory storage if storage quota is exceeded or in private mode).
+2. **Optimistic Updates**:
+   - Roll back optimistic UI changes cleanly if the underlying API mutation fails. Always display actionable retry prompts.
+

actdim_along-4.9.0/.along/.migration-backup/2026-11-14-230651/.along/scripts/build.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# Status: verified
+"""
+build.py - Automated Project Build Hook for along repository.
+Builds frontend assets and validates code distribution artifacts.
+"""
+
+import sys
+import os
+import shutil
+import subprocess
+
+def main():
+    repo_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    ui_dir = os.path.join(repo_root, "packages", "dashboard-ui")
+    
+    # If UI package exists, compile via pnpm if available
+    if os.path.exists(ui_dir):
+        pnpm = shutil.which("pnpm")
+        if pnpm:
+            print("-> Building dashboard UI via pnpm...")
+            res = subprocess.run([pnpm, "--filter", "@along/dashboard-ui", "build"], cwd=repo_root)
+            if res.returncode != 0:
+                sys.exit(res.returncode)
+    
+    print("-> Build verification completed successfully.")
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

actdim_along-4.9.0/.along/.migration-backup/2026-11-14-230651/.along/scripts/dev.py

@@ -0,0 +1,80 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "fastapi>=0.110.0",
+#     "uvicorn>=0.28.0",
+#     "pydantic>=2.0.0",
+#     "pyyaml>=6.0.0",
+#     "rich>=13.0.0",
+# ]
+# ///
+
+"""
+Along Development Runner (.along/scripts/dev.py).
+Launches the full dev environment with Vite HMR frontend (port 5173) and live FastAPI backend (port 8765).
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Auto-bootstrap with `uv run` if dependencies are not available in current interpreter
+if "--no-uv-reentry" not in sys.argv:
+    try:
+        import fastapi
+        import uvicorn
+        import pydantic
+    except ImportError:
+        uv_bin = shutil.which("uv")
+        if uv_bin:
+            cmd = [uv_bin, "run", str(Path(__file__).resolve())] + sys.argv[1:] + ["--no-uv-reentry"]
+            try:
+                sys.exit(subprocess.call(cmd))
+            except KeyboardInterrupt:
+                sys.exit(0)
+        else:
+            print(
+                "[Error] Missing dependencies (fastapi, uvicorn, pydantic).\n"
+                "Run with uv (recommended):\n"
+                "    uv run .along/scripts/dev.py\n"
+                "Or install the required packages:\n"
+                "    python -m pip install fastapi uvicorn pydantic pyyaml rich",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+
+if "--no-uv-reentry" in sys.argv:
+    sys.argv.remove("--no-uv-reentry")
+
+# Add repo root and scripts/ to sys.path
+repo_root = Path(__file__).resolve().parent.parent.parent
+if str(repo_root) not in sys.path:
+    sys.path.insert(0, str(repo_root))
+
+scripts_dir = repo_root / "scripts"
+if str(scripts_dir) not in sys.path:
+    sys.path.insert(0, str(scripts_dir))
+
+from alongkit import bootstrap
+bootstrap.ensure_deps()
+
+from dashboard.app import main
+
+if __name__ == "__main__":
+    if any(a in ("--setup-env", "--env-setup") for a in sys.argv):
+        from alongkit import devenv
+        reinstall = "--reinstall" in sys.argv
+        ok, msg = devenv.setup_dev_environment(str(repo_root), reinstall=reinstall)
+        if not ok:
+            print(f"[Error] Dev environment setup failed: {msg}", file=sys.stderr)
+            sys.exit(1)
+        print(f"-> {msg}")
+        sys.exit(0)
+
+    # Default to dev mode if no explicit mode arguments passed
+    if len(sys.argv) == 1 or (len(sys.argv) == 2 and sys.argv[1] not in ("-w", "--web", "-c", "--cli", "--export")):
+        sys.argv.append("--dev")
+    main()
+