kctl-outline 0.6.1__tar.gz

kctl_outline-0.6.1/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_outline-0.6.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: kctl-outline
+Version: 0.6.1
+Summary: Kodemeio Outline CLI — manage Outline wiki instances and sync markdown docs
+Author-email: Kodemeio <dev@kodeme.io>
+License-Expression: MIT
+Keywords: cli,knowledge-base,kodemeio,outline,wiki
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.7.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kctl-outline
+
+Kodemeio Outline CLI — manages Outline wiki instances and syncs markdown documentation between git repositories and one or more Outline collections.
+
+## Install
+
+```bash
+cd packages/kctl-outline
+uv sync --extra dev
+uv run kctl-outline --help
+```
+
+Or via the workspace from the repo root:
+
+```bash
+uv sync
+uv run --package kctl-outline kctl-outline --help
+```
+
+## Configuration
+
+Like other `kctl-*` tools, configuration lives at `~/.config/kodemeio/config.yaml`. Each profile may declare an `outline` service block:
+
+```yaml
+profiles:
+  kod:
+    outline:
+      url: https://outline.kodeme.io
+      token: env:OUTLINE_API_TOKEN_KOD
+  tpp:
+    outline:
+      url: https://outline.idtpp.com
+      token: env:OUTLINE_API_TOKEN_TPP
+```
+
+Add a profile interactively:
+
+```bash
+kctl-outline config init
+kctl-outline config add tpp --url https://outline.idtpp.com --token <TOKEN>
+kctl-outline config use kod
+```
+
+## Commands
+
+| Group | Purpose |
+|---|---|
+| `documents` | List, create, update, delete, move documents |
+| `collections` | Manage collections |
+| `users`, `groups` | User and group management |
+| `shares` | Public share links |
+| `comments`, `events`, `revisions` | Read-only metadata |
+| `templates`, `stars`, `tokens` | Misc admin |
+| `health`, `dashboard`, `doctor` | Diagnostics (`doctor` checks URL + auth config) |
+| `search` | Search across documents |
+| `sync` | **Sync markdown docs between repos and Outline (see below)** |
+
+## Sync subcommand
+
+`kctl-outline sync` is the primary integration point with `kodemeio-docs`. It supports multi-mapping configs (`.outline-sync.yaml` v2) with three direction modes:
+
+- **`push`** — git is the source of truth. Markdown files are pushed to Outline.
+- **`pull`** — Outline is the source of truth. Documents are pulled into the repo.
+- **`mixed`** — per-file `.ssot` markers decide direction.
+
+```bash
+# Dry-run a sync from a repo
+kctl-outline sync run /path/to/kodemeio-docs --config .outline-sync.kod.yaml
+
+# Apply
+kctl-outline sync run /path/to/kodemeio-docs --config .outline-sync.kod.yaml --no-dry-run
+
+# Filter to a specific direction
+kctl-outline sync run . --config .outline-sync.kod.yaml --mode push --no-dry-run
+
+# Inspect tracked state
+kctl-outline sync status
+kctl-outline sync diff /path/to/repo
+```
+
+The full spec lives in `kodemeio-docs/superpowers/specs/2026-04-10-docs-outline-restructure-design.md`.
+
+## Profile-aware sync routing
+
+When a sync config declares `profile: tpp`, `kctl-outline sync run` builds a fresh client using that profile's URL and token, regardless of the active CLI profile. This means the same machine can push to both `outline.kodeme.io` and `outline.idtpp.com` without switching profiles between commands.
+
+## Layout
+
+```
+packages/kctl-outline/
+├── pyproject.toml
+├── README.md
+├── src/kctl_outline/
+│   ├── cli.py            # Typer entry point
+│   ├── commands/         # one module per Outline subresource
+│   │   ├── sync.py       # the Plan A/D sync subcommand
+│   │   ├── documents.py
+│   │   ├── collections.py
+│   │   └── …
+│   └── core/
+│       ├── client.py     # httpx wrapper
+│       ├── config.py     # profile resolution
+│       ├── sync_config.py    # SyncConfig v2 schema + v1 auto-upgrade
+│       ├── sync_planner.py   # pure plan_push_mapping
+│       ├── sync_pull.py      # pull direction (Outline → disk)
+│       ├── sync_state.py     # MappingSyncEntry + v1→v2 migration
+│       └── sync_ssot.py      # .ssot marker walker
+└── tests/                # 30+ tests (pytest)
+```
+
+## Tests
+
+```bash
+cd packages/kctl-outline
+uv run --extra dev pytest tests/ -v
+```

kctl_outline-0.6.1/README.md

@@ -0,0 +1,116 @@
+# kctl-outline
+
+Kodemeio Outline CLI — manages Outline wiki instances and syncs markdown documentation between git repositories and one or more Outline collections.
+
+## Install
+
+```bash
+cd packages/kctl-outline
+uv sync --extra dev
+uv run kctl-outline --help
+```
+
+Or via the workspace from the repo root:
+
+```bash
+uv sync
+uv run --package kctl-outline kctl-outline --help
+```
+
+## Configuration
+
+Like other `kctl-*` tools, configuration lives at `~/.config/kodemeio/config.yaml`. Each profile may declare an `outline` service block:
+
+```yaml
+profiles:
+  kod:
+    outline:
+      url: https://outline.kodeme.io
+      token: env:OUTLINE_API_TOKEN_KOD
+  tpp:
+    outline:
+      url: https://outline.idtpp.com
+      token: env:OUTLINE_API_TOKEN_TPP
+```
+
+Add a profile interactively:
+
+```bash
+kctl-outline config init
+kctl-outline config add tpp --url https://outline.idtpp.com --token <TOKEN>
+kctl-outline config use kod
+```
+
+## Commands
+
+| Group | Purpose |
+|---|---|
+| `documents` | List, create, update, delete, move documents |
+| `collections` | Manage collections |
+| `users`, `groups` | User and group management |
+| `shares` | Public share links |
+| `comments`, `events`, `revisions` | Read-only metadata |
+| `templates`, `stars`, `tokens` | Misc admin |
+| `health`, `dashboard`, `doctor` | Diagnostics (`doctor` checks URL + auth config) |
+| `search` | Search across documents |
+| `sync` | **Sync markdown docs between repos and Outline (see below)** |
+
+## Sync subcommand
+
+`kctl-outline sync` is the primary integration point with `kodemeio-docs`. It supports multi-mapping configs (`.outline-sync.yaml` v2) with three direction modes:
+
+- **`push`** — git is the source of truth. Markdown files are pushed to Outline.
+- **`pull`** — Outline is the source of truth. Documents are pulled into the repo.
+- **`mixed`** — per-file `.ssot` markers decide direction.
+
+```bash
+# Dry-run a sync from a repo
+kctl-outline sync run /path/to/kodemeio-docs --config .outline-sync.kod.yaml
+
+# Apply
+kctl-outline sync run /path/to/kodemeio-docs --config .outline-sync.kod.yaml --no-dry-run
+
+# Filter to a specific direction
+kctl-outline sync run . --config .outline-sync.kod.yaml --mode push --no-dry-run
+
+# Inspect tracked state
+kctl-outline sync status
+kctl-outline sync diff /path/to/repo
+```
+
+The full spec lives in `kodemeio-docs/superpowers/specs/2026-04-10-docs-outline-restructure-design.md`.
+
+## Profile-aware sync routing
+
+When a sync config declares `profile: tpp`, `kctl-outline sync run` builds a fresh client using that profile's URL and token, regardless of the active CLI profile. This means the same machine can push to both `outline.kodeme.io` and `outline.idtpp.com` without switching profiles between commands.
+
+## Layout
+
+```
+packages/kctl-outline/
+├── pyproject.toml
+├── README.md
+├── src/kctl_outline/
+│   ├── cli.py            # Typer entry point
+│   ├── commands/         # one module per Outline subresource
+│   │   ├── sync.py       # the Plan A/D sync subcommand
+│   │   ├── documents.py
+│   │   ├── collections.py
+│   │   └── …
+│   └── core/
+│       ├── client.py     # httpx wrapper
+│       ├── config.py     # profile resolution
+│       ├── sync_config.py    # SyncConfig v2 schema + v1 auto-upgrade
+│       ├── sync_planner.py   # pure plan_push_mapping
+│       ├── sync_pull.py      # pull direction (Outline → disk)
+│       ├── sync_state.py     # MappingSyncEntry + v1→v2 migration
+│       └── sync_ssot.py      # .ssot marker walker
+└── tests/                # 30+ tests (pytest)
+```
+
+## Tests
+
+```bash
+cd packages/kctl-outline
+uv run --extra dev pytest tests/ -v
+```

kctl_outline-0.6.1/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-outline"
+version = "0.6.1"
+description = "Kodemeio Outline CLI — manage Outline wiki instances and sync markdown docs"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Kodemeio", email = "dev@kodeme.io" }]
+keywords = ["outline", "wiki", "knowledge-base", "cli", "kodemeio"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "kctl-lib>=0.7.0",
+    "typer>=0.15.0",
+    "httpx>=0.28.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-outline = "kctl_outline.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_outline"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kctl_outline-0.6.1/skills/outline-admin/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: outline-admin
+description: >
+  Outline wiki/knowledge-base administration via kctl-outline CLI.
+  MUST use for ANY kctl-outline operation — documents, collections, users, groups,
+  shares, comments, events, health checks, AND markdown sync between repos and
+  one or more Outline instances.
+  Triggers on: "kctl-outline", "outline", "wiki", "knowledge base", "create document",
+  "collection", "share document", "outline.kodeme.io", "outline.idtpp.com",
+  "sync docs", "outline sync", "doc sync", ".outline-sync.yaml".
+---
+
+# outline-admin — kctl-outline CLI Reference
+
+## Overview
+
+**CLI:** `kctl-outline`
+**Workspace:** `kodemeio-platform/packages/kctl-outline/`
+**Install:** `cd packages/kctl-outline && uv sync --extra dev`
+**Standalone install:** `uv tool install kctl-outline` (when published to PyPI)
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output |
+| `--quiet`, `-q` | Suppress info messages |
+| `--profile`, `-p` | Profile name (default from `~/.config/kodemeio/config.yaml`) |
+| `--url` | Override API URL (e.g., `https://outline.idtpp.com`) |
+| `--token` | Override API token |
+| `--version`, `-V` | Show version |
+
+## Profiles
+
+Configure once per Outline instance:
+
+```bash
+kctl-outline config init                                                # interactive
+kctl-outline config add kod --url https://outline.kodeme.io --token <T>
+kctl-outline config add tpp --url https://outline.idtpp.com --token <T>
+kctl-outline config use kod                                             # default
+kctl-outline config current                                             # show active
+```
+
+## Command Groups
+
+| Group | Purpose |
+|---|---|
+| `config` | Profile management (init, add, use, show, profiles, current, test) |
+| `documents` | Create / list / update / delete / move documents |
+| `collections` | Manage collections |
+| `users` | User management |
+| `groups` | Group management |
+| `shares` | Public share links |
+| `comments`, `events`, `revisions` | Read-only metadata |
+| `templates`, `stars`, `tokens` | Misc admin |
+| `search` | Search across documents |
+| `health` | Health checks and diagnostics |
+| `dashboard` | System overview |
+| **`sync`** | **Markdown sync between git repos and Outline (primary integration)** |
+
+## Sync subcommand — primary use case
+
+`kctl-outline sync` is the integration point with `kodemeio-docs`. It supports multi-mapping `.outline-sync.yaml` v2 configs with three direction modes:
+
+- **`push`** — git is the source of truth. Markdown files are pushed to Outline.
+- **`pull`** — Outline is the source of truth. Documents are pulled into the repo. Reconciles deletions: docs removed in Outline are also removed from disk.
+- **`mixed`** — per-file `.ssot` markers (containing `git` or `outline`) decide direction.
+
+### Commands
+
+```bash
+# Dry-run (default) against the kod instance
+kctl-outline sync run /path/to/kodemeio-docs --config .outline-sync.kod.yaml
+
+# Apply
+kctl-outline sync run /path/to/kodemeio-docs --config .outline-sync.kod.yaml --no-dry-run
+
+# Filter to one direction (push only, skip pull mappings)
+kctl-outline sync run . --config .outline-sync.kod.yaml --mode push --no-dry-run
+
+# Same syntax against the TPP instance
+kctl-outline sync run /path/to/kodemeio-docs --config .outline-sync.tpp.yaml --no-dry-run
+
+# Inspect tracked state
+kctl-outline sync status
+
+# What would change on next push?
+kctl-outline sync diff /path/to/kodemeio-docs
+
+# Bootstrap a config stub
+kctl-outline sync init /path/to/repo --collection 'My Docs'
+
+# Wipe state (does NOT delete from Outline)
+kctl-outline sync reset --force
+```
+
+### Profile-aware client routing
+
+When a sync config declares `profile: tpp`, `sync run` builds a fresh client using **that profile's URL+token**, regardless of the active CLI profile. So the same machine can push to both `outline.kodeme.io` and `outline.idtpp.com` without `--profile` switching:
+
+```bash
+kctl-outline sync run . --config .outline-sync.kod.yaml --no-dry-run    # → outline.kodeme.io
+kctl-outline sync run . --config .outline-sync.tpp.yaml --no-dry-run    # → outline.idtpp.com
+```
+
+### .outline-sync.yaml v2 schema
+
+```yaml
+instance: outline.kodeme.io       # human-readable, optional
+profile: kod                      # selects the kctl-outline profile
+
+mappings:
+  - src: shared/                  # path relative to the config file
+    collection: "Shared — Engineering"
+    mode: push                    # push | pull | mixed
+    subpath: ""                   # optional: nest under a doc title
+    include:                      # optional gitignore-style globs
+      - "01-*/**"
+      - "02-*/**"
+    exclude:                      # optional
+      - "**/draft/**"
+
+  - src: shared/06-business-processes
+    collection: "Shared — Business"
+    mode: pull                    # nightly cron pulls + reconciles deletions
+
+  - src: tenants/kod
+    collection: "Kod — Internal"
+    mode: mixed                   # per-file .ssot markers
+```
+
+### .ssot markers
+
+Each leaf directory may contain a `.ssot` file with exactly one line: `git` or `outline`. In `mixed` mode the planner skips push actions for files under `outline`-marked directories (and vice versa). The kodemeio-docs pre-commit hook (`scripts/check_ssot.py`) enforces the same rule on commits.
+
+## Live URLs
+
+| Profile | URL | Audience |
+|---|---|---|
+| `kod` | https://outline.kodeme.io | Kodemeio staff, MAC, Provetics, Terakidz |
+| `tpp` | https://outline.idtpp.com | TPP Group customer-facing |
+
+## Tests
+
+```bash
+cd packages/kctl-outline
+uv run --extra dev pytest tests/ -v
+# Expected: 32 tests passing
+```
+
+## See also
+
+- Spec: `kodemeio-docs/superpowers/specs/2026-04-10-docs-outline-restructure-design.md`
+- Plans: `kodemeio-docs/superpowers/plans/2026-04-10-{docs-restructure,kctl-outline-sync-enhancements,outline-tpp-instance}.md`
+- Configs in use: `kodemeio-docs/.outline-sync.{kod,tpp}.yaml`
+- Push CI: `kodemeio-docs/.github/workflows/outline-sync-push.yml`
+- Nightly pull cron: `kodemeio-docs/scripts/cron/outline-sync-pull.sh`

kctl_outline-0.6.1/src/kctl_outline/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-outline: Kodemeio Outline CLI."""
+
+__version__ = "0.6.1"

kctl_outline-0.6.1/src/kctl_outline/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m kctl_outline."""
+
+from kctl_outline.cli import app
+
+app()

kctl_outline-0.6.1/src/kctl_outline/cli.py

@@ -0,0 +1,120 @@
+"""Main CLI entry point for kctl-outline."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+from kctl_outline import __version__
+from kctl_outline.commands.attachments import app as attachments_app
+from kctl_outline.commands.collections import app as collections_app
+from kctl_outline.commands.comments import app as comments_app
+from kctl_outline.commands.config_cmd import app as config_app
+from kctl_outline.commands.dashboard import app as dashboard_app
+from kctl_outline.commands.doctor_cmd import app as doctor_app
+from kctl_outline.commands.documents import app as documents_app
+from kctl_outline.commands.events import app as events_app
+from kctl_outline.commands.groups import app as groups_app
+from kctl_outline.commands.health import app as health_app
+from kctl_outline.commands.revisions import app as revisions_app
+from kctl_outline.commands.search import search_command
+from kctl_outline.commands.shares import app as shares_app
+from kctl_outline.commands.stars import app as stars_app
+from kctl_outline.commands.sync import app as sync_app
+from kctl_outline.commands.templates import app as templates_app
+from kctl_outline.commands.tokens import app as tokens_app
+from kctl_outline.commands.users import app as users_app
+from kctl_outline.core.callbacks import AppContext
+from kctl_outline.core.exceptions import APIError, AuthenticationError, ConfigError, KctlError
+from kctl_outline.core.exceptions import ConnectionError as KctlConnectionError
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-outline {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-outline",
+    help="Kodemeio Outline CLI - manage your Outline wiki instances.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    url: Annotated[str | None, typer.Option("--url", help="API URL override")] = None,
+    token: Annotated[str | None, typer.Option("--token", help="API token override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Outline CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        url_override=url,
+        token_override=token,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-outline", __version__)
+
+
+# Register all command groups
+app.add_typer(documents_app, name="documents")
+app.add_typer(collections_app, name="collections")
+app.add_typer(users_app, name="users")
+app.add_typer(groups_app, name="groups")
+app.add_typer(shares_app, name="shares")
+app.add_typer(comments_app, name="comments")
+app.add_typer(events_app, name="events")
+app.add_typer(health_app, name="health")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(config_app, name="config")
+app.add_typer(doctor_app, name="doctor")
+app.add_typer(stars_app, name="stars")
+app.add_typer(templates_app, name="templates")
+app.add_typer(revisions_app, name="revisions")
+app.add_typer(attachments_app, name="attachments")
+app.add_typer(tokens_app, name="tokens")
+app.add_typer(sync_app, name="sync")
+add_tui_command(app, service_key="outline", version=__version__)
+
+# Top-level search command
+app.command("search")(search_command)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlConnectionError as e:
+        typer.echo(f"Connection error: {e}", err=True)
+        raise typer.Exit(1) from e
+    except AuthenticationError as e:
+        typer.echo(f"Auth error: {e}", err=True)
+        raise typer.Exit(1) from e
+    except APIError as e:
+        typer.echo(f"API error: {e}", err=True)
+        raise typer.Exit(1) from e
+    except ConfigError as e:
+        typer.echo(f"Config error: {e}", err=True)
+        raise typer.Exit(1) from e
+    except KctlError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from e
+
+
+if __name__ == "__main__":
+    _run()