meridian-cli 0.3.30__tar.gz → 0.3.32__tar.gz

{meridian_cli-0.3.30 → meridian_cli-0.3.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meridian-cli
-Version: 0.3.30
+Version: 0.3.32
 Summary: Orchestrate CLI + MCP server for multi-model agent workflows
 Project-URL: Homepage, https://github.com/haowjy/meridian-cli
 Project-URL: Repository, https://github.com/haowjy/meridian-cli

{meridian_cli-0.3.30 → meridian_cli-0.3.32}/src/meridian/AGENTS.md

@@ -61,6 +61,7 @@ config entry. If adding a feature requires editing 10 files, the abstraction is
 | `lib/context/` | Context resolution (KB, strategy, work directories) |
 | `lib/hooks/` | Hook dispatch, config layering, built-in hooks |
 | `lib/extensions/` | Extension command registry |
+| `lib/artifact/` | Detached static-artifact serving over Tailscale (`artifact serve/list/stop/gc`); no daemon — file is authority |
 
 | `lib/observability/` | Spawn-scoped JSONL tracing |
 | `lib/mermaid/` | Mermaid diagram validation |

{meridian_cli-0.3.30 → meridian_cli-0.3.32}/src/meridian/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.30"
+__version__ = "0.3.32"

{meridian_cli-0.3.30 → meridian_cli-0.3.32}/src/meridian/cli/app_tree.py

@@ -50,6 +50,7 @@ config_app = _group_app("config")
 workspace_app = _group_app("workspace")
 kg_app = _group_app("kg")
 mermaid_app = _group_app("mermaid")
+artifact_app = _group_app("artifact")
 qi_app = _group_app("qi")
 telemetry_app = _group_app("telemetry")
 completion_app = _group_app("completion")
@@ -69,6 +70,7 @@ app.command(config_app, name="config")
 app.command(workspace_app, name="workspace")
 app.command(kg_app, name="kg")
 app.command(mermaid_app, name="mermaid")
+app.command(artifact_app, name="artifact")
 app.command(qi_app, name="qi")
 app.command(telemetry_app, name="telemetry")
 app.command(completion_app, name="completion")
@@ -88,6 +90,7 @@ for _group_name, _group_app_obj in {
     "workspace": workspace_app,
     "kg": kg_app,
     "mermaid": mermaid_app,
+    "artifact": artifact_app,
     "qi": qi_app,
     "telemetry": telemetry_app,
     "completion": completion_app,
@@ -97,6 +100,7 @@ for _group_name, _group_app_obj in {
 
 __all__ = [
     "app",
+    "artifact_app",
     "completion_app",
     "config_app",
     "context_app",

meridian_cli-0.3.32/src/meridian/cli/artifact_cmd.py

@@ -0,0 +1,193 @@
+"""CLI handlers for ``meridian artifact``."""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated, Never
+
+from cyclopts import Parameter
+
+from meridian.cli.app_tree import artifact_app
+from meridian.lib.artifact import service
+from meridian.lib.artifact.store import Serve, load_serves
+
+_DEFAULT_TTL = f"{service.DEFAULT_TTL_SECONDS // 3600}h"
+
+
+@artifact_app.default
+def cmd_artifact_root() -> None:
+    """Show artifact serving help."""
+    print(
+        """Serve static artifacts over Tailscale.
+
+Commands:
+  meridian artifact serve [dir]   Serve a directory (default TTL: 2h)
+  meridian artifact list          List recorded artifact serves
+  meridian artifact stop <slug>   Stop one artifact serve
+  meridian artifact gc            Stop expired artifact serves"""
+    )
+    raise SystemExit(0)
+
+
+def _fail(message: str, code: int = 1) -> Never:
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _duration(seconds: float) -> str:
+    seconds = max(0, int(seconds))
+    if seconds >= 86400:
+        return f"{seconds / 86400:.1f}d"
+    if seconds >= 3600:
+        return f"{seconds / 3600:.1f}h"
+    if seconds >= 60:
+        return f"{seconds / 60:.1f}m"
+    return f"{seconds}s"
+
+
+def _created_at(serve: Serve) -> datetime:
+    try:
+        return datetime.fromisoformat(serve.created.removesuffix("Z") + "+00:00")
+    except ValueError:
+        return datetime.now(UTC)
+
+
+@artifact_app.command(name="serve")
+def cmd_artifact_serve(
+    directory: Annotated[Path, Parameter(help="Directory to serve.")] = Path("."),
+    *,
+    ttl: Annotated[
+        str, Parameter(name="--ttl", help="Lifetime: 30m, 2h, 90s, or 1d.")
+    ] = _DEFAULT_TTL,
+    persistent: Annotated[
+        bool, Parameter(name="--persistent", help="Never expire automatically.")
+    ] = False,
+    funnel: Annotated[
+        bool, Parameter(name="--funnel", help="Expose publicly with Tailscale Funnel.")
+    ] = False,
+    slug: Annotated[
+        str | None, Parameter(name="--slug", help="URL path name (default: directory name).")
+    ] = None,
+    port: Annotated[
+        int | None,
+        Parameter(name="--port", help="Serve on this port instead of a random one."),
+    ] = None,
+) -> None:
+    """Serve a directory over Tailscale."""
+    resolved = directory.expanduser().resolve()
+    if not resolved.exists():
+        _fail(f"directory not found: {directory}", 2)
+    if not resolved.is_dir():
+        _fail(f"not a directory: {directory}", 2)
+    if port is not None:
+        if port < 1 or port > 65535:
+            _fail("--port must be between 1 and 65535", 2)
+        if port < 1024:
+            _fail("--port must be >= 1024 (do not claim well-known ports)", 2)
+    try:
+        ttl_seconds = None if persistent else service.parse_ttl(ttl)
+        serve, url = service.start_serve(
+            resolved, ttl_seconds=ttl_seconds, funnel=funnel, slug=slug, port=port
+        )
+    except service.PortInUseError as exc:
+        _fail(str(exc), 2)
+    except (service.ArtifactError, OSError) as exc:
+        _fail(str(exc))
+    ttl_hint = "persistent" if serve.ttl_seconds is None else _duration(serve.ttl_seconds)
+    print(url)
+    print(
+        f"pid {serve.pid} · TTL {ttl_hint} · stop with: meridian artifact stop {serve.slug}"
+    )
+
+
+@artifact_app.command(name="list")
+def cmd_artifact_list(
+    *,
+    fmt: Annotated[
+        str, Parameter(name="--format", help="Output format: text or json.")
+    ] = "text",
+) -> None:
+    """List recorded artifact serves without changing state."""
+    from meridian.cli.main import get_global_options
+
+    serves = load_serves()
+    effective_fmt = "json" if get_global_options().output.format == "json" else fmt
+    if effective_fmt == "json":
+        print(json.dumps([asdict(serve) for serve in serves], indent=2))
+        return
+    if effective_fmt != "text":
+        _fail("--format must be text or json", 2)
+    if not serves:
+        print("No active artifact serves.")
+        return
+    now = datetime.now(UTC)
+    try:
+        dns_name = service.tailscale_dns_name()
+    except (service.ArtifactError, OSError) as exc:
+        dns_name = None
+        print(f"Warning: artifact URLs unavailable: {exc}", file=sys.stderr)
+    print(f"{'SLUG':<22} {'LOCAL':<7} {'ALIVE':<6} {'AGE':<8} {'TTL':<11} {'DIRECTORY':<30} URL")
+    for serve in serves:
+        created = _created_at(serve)
+        age = _duration((now - created).total_seconds())
+        ttl = (
+            "persistent"
+            if serve.ttl_seconds is None
+            else _duration(serve.ttl_seconds - (now - created).total_seconds())
+        )
+        public_port = service.tailnet_port(serve.local_port, funnel=serve.funnel)
+        url = (
+            f"https://{dns_name}:{public_port}/{serve.slug}/"
+            if dns_name
+            else "unavailable"
+        )
+        alive = (
+            "yes"
+            if service.pid_alive(serve.pid, serve.process_created_at)
+            else "no"
+        )
+        print(
+            f"{serve.slug:<22} {serve.local_port:<7} {alive:<6} {age:<8} "
+            f"{ttl:<11} {serve.dir:<30} {url}"
+        )
+
+
+@artifact_app.command(name="stop")
+def cmd_artifact_stop(
+    slug: Annotated[str, Parameter(help="Slug (or local port) of the serve to stop.")],
+) -> None:
+    """Stop one artifact serve."""
+    try:
+        stopped = service.stop_serve(slug)
+    except (service.ArtifactError, OSError) as exc:
+        _fail(str(exc))
+    if stopped:
+        print(f"Stopped artifact serve {slug}.")
+    else:
+        print(f"No artifact serve recorded as {slug}.")
+
+
+@artifact_app.command(name="gc")
+def cmd_artifact_gc() -> None:
+    """Stop and remove expired artifact serves."""
+    try:
+        expired, failed = service.sweep_expired()
+    except (service.ArtifactError, OSError) as exc:
+        _fail(str(exc))
+    print(f"Garbage-collected {len(expired)} expired artifact serve(s).")
+    if failed:
+        print(f"Failed to remove: {', '.join(failed)}", file=sys.stderr)
+        raise SystemExit(1)
+
+
+__all__ = [
+    "cmd_artifact_gc",
+    "cmd_artifact_list",
+    "cmd_artifact_root",
+    "cmd_artifact_serve",
+    "cmd_artifact_stop",
+]

{meridian_cli-0.3.30 → meridian_cli-0.3.32}/src/meridian/cli/command_groups.py

@@ -132,6 +132,13 @@ _GROUP_HELP: dict[str, GroupHelp] = {
         long_help='Mermaid diagram validation: extract and check diagram syntax in\nmarkdown files and standalone .mmd/.mermaid files.',
         examples=(('meridian mermaid check', ''), ('meridian mermaid check docs/', ''), ('meridian mermaid check diagram.mmd', '')),
     ),
+    "artifact": GroupHelp(
+        summary='Share static artifacts over Tailscale.',
+        long_help='Serve a local directory over Tailscale as a temporary, tailnet-scoped URL.',
+        examples=(('meridian artifact serve .', ''), ('meridian artifact list', '')),
+        agent_notes='URLs are tailnet-only — the recipient must be on your tailnet; use --funnel for a public URL (rare). Serves expire after 2h by default; --persistent keeps one, stop/gc remove them. Point it at a built structured-artifact directory to share with a human or another agent.',
+        agent_subcommands=('serve', 'list', 'stop', 'gc'),
+    ),
     "telemetry": GroupHelp(
         summary='Telemetry inspection: tail, query, and status over local segments.',
         long_help='Telemetry inspection: tail, query, and status over local segments.\n\nNote: Rootless MCP stdio server processes write telemetry to stderr only and are not visible in local segment readers.',
@@ -274,6 +281,14 @@ COMMAND_GROUP_SPECS: dict[str, CommandGroupSpec] = {
         registration_bucket='mermaid',
         has_group_app=True,
     ),
+    "artifact": CommandGroupSpec(
+        help=_GROUP_HELP["artifact"],
+        agent_root_description='Share a directory as a temporary Tailscale URL for humans or other agents.',
+        agent_root=True,
+        human_root_order=17,
+        registration_bucket='artifact',
+        has_group_app=True,
+    ),
     "telemetry": CommandGroupSpec(
         help=_GROUP_HELP["telemetry"],
         human_root_order=12,

{meridian_cli-0.3.30 → meridian_cli-0.3.32}/src/meridian/cli/main.py

@@ -748,6 +748,11 @@ def _register_commands_for_invocation(argv: Sequence[str]) -> None:
 
             _ = _mermaid_cmd
 
+        def _register_artifact() -> None:
+            import meridian.cli.artifact_cmd as _artifact_cmd
+
+            _ = _artifact_cmd
+
         def _register_qi() -> None:
             import meridian.cli.qi_cmd as _qi_cmd
 
@@ -780,6 +785,7 @@ def _register_commands_for_invocation(argv: Sequence[str]) -> None:
             "sync": _register_sync,
             "kg": _register_kg,
             "mermaid": _register_mermaid,
+            "artifact": _register_artifact,
             "qi": _register_qi,
             "report": _register_report,
             "migrate": _register_migrate,

{meridian_cli-0.3.30 → meridian_cli-0.3.32}/src/meridian/cli/startup/catalog.py

@@ -496,6 +496,10 @@ _COMMAND_DESCRIPTORS: tuple[CommandDescriptor, ...] = (
     _read_rootless(("kg", "graph"), "Render knowledge graph."),
     _read_rootless(("kg", "check"), "Check knowledge graph links."),
     _read_rootless(("mermaid", "check"), "Check Mermaid diagrams."),
+    _write_rootless(("artifact", "serve"), "Serve a directory over tailscale."),
+    _read_rootless(("artifact", "list"), "List active artifact serves."),
+    _write_rootless(("artifact", "stop"), "Stop an artifact serve."),
+    _write_rootless(("artifact", "gc"), "Garbage-collect expired artifact serves."),
     _read_rootless(("qi",), "Show inline knowledge for current path."),
     _read_rootless(("qi", "list"), "List all inline knowledge locations."),
     _read_rootless(("qi", "check"), "Check inline knowledge health."),

meridian_cli-0.3.32/src/meridian/lib/artifact/AGENTS.md

@@ -0,0 +1,67 @@
+# lib/artifact/ — Detached Artifact Serving
+
+Thin wrapper that serves a static artifact directory over Tailscale. No daemon:
+`meridian artifact serve` launches a detached stdlib HTTP server, registers a
+Tailscale serve path, records state, and exits. `list`/`stop`/`gc` read and prune
+that state. The CLI is the only entry point; nothing else imports this package.
+
+## Mental model
+
+```
+artifact serve <dir>
+  → launch_http_server():  _serve_dir on 127.0.0.1:<port>  (setsid, detached)
+  → _tailscale_register():  tailscale serve --https=<port> --set-path /<slug> → 127.0.0.1:<port>
+  → record Serve in ~/.meridian/serves.json, print URL, exit
+```
+
+The server outlives the CLI by design ("share and walk away"). Cleanup is TTL +
+lazy GC on every `serve`/`gc`, and explicit `stop`. State is the file; there is no
+in-memory handle between commands.
+
+## Key invariants
+
+- **Never serve on 443 or well-known ports.** The CLI rejects ports < 1024 and
+  defaults to random 49152–65535; `_tailscale_register` always passes an explicit
+  `--https=<port>`. Portless 443 does not route to local serve handlers on some
+  nodes, and claiming well-known ports clobbers unrelated serves. See KB
+  `research/tailscale-serve-semantics.md`.
+- **Teardown is per-path only.** `tailscale_off` runs
+  `tailscale serve --https=<port> --set-path=/<slug> off` — removes ONE slug.
+  Never bare `--https=<port> off` (drops all slugs on the port) or `serve reset`
+  (wipes the whole node). Only remove slugs recorded in serves.json.
+- **`tailscale serve --set-path` forwards the full path.** `_serve_dir.py` strips
+  the `/<slug>` prefix in `translate_path` so root-serving backends resolve. Strip
+  in path translation, not URL rewriting, so directory redirects keep the prefix.
+- **No parent-death linkage.** `launch_http_server` uses `start_new_session=True`
+  (POSIX) / `DETACHED_PROCESS` (Windows) with no `pdeathsig`. Adding linkage breaks
+  the feature: TTL + lazy GC *is* the cleanup mechanism.
+- **Validate the slug at every trust boundary** before any Tailscale subprocess.
+  A malformed/empty slug would produce `--set-path=/ off` and clobber a root
+  handler. `is_valid_slug` runs at registration, teardown, URL build, and load.
+- **State is atomic and locked.** `serves.json` writes go through
+  `atomic_write_text`; reads tolerate truncation/missing; `start_serve`,
+  `stop_serve`, and `sweep_expired` hold `serves.json.lock` across
+  read-modify-save. `Serve.process_created_at` (birth epoch) guards PID-reuse
+  from terminating an unrelated process tree.
+
+## Anti-patterns
+
+- Don't add a daemon or keep an in-memory handle between commands — the file is
+  the authority and `list`/`stop`/`gc` run in fresh processes.
+- Don't pick the local bind port independently of the Tailscale `--https` port;
+  they are the same number, and it must avoid serves.json, live
+  `tailscale serve status --json`, and an EADDRINUSE probe.
+- `--funnel` exposes publicly on the fixed Funnel port **10000** (Funnel allows
+  only 443/8443/10000; 443 is portless-broken and 8443 is commonly taken). The
+  local backend keeps its own random/`--port` high port; `tailnet_port()` derives
+  the public port from the funnel flag. If Funnel isn't enabled on the tailnet the
+  register call fails loudly (ArtifactError) and rolls back — no orphan state.
+- Don't reset/abort a GC sweep on a single terminate failure — each serve is
+  independent; a failed teardown must preserve its entry, not stop the loop.
+
+## Related
+
+- [../../AGENTS.md](../../AGENTS.md) — package layers; this package is a leaf,
+  not part of the ops/launch/state spine
+- KB `research/tailscale-serve-semantics.md` — Tailscale routing/teardown facts
+  behind the invariants above

meridian_cli-0.3.32/src/meridian/lib/artifact/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

meridian_cli-0.3.32/src/meridian/lib/artifact/__init__.py

@@ -0,0 +1,19 @@
+"""Static artifact serving over Tailscale."""
+
+from meridian.lib.artifact.store import (
+    Serve,
+    is_valid_slug,
+    load_serves,
+    save_serves,
+    serves_lock_path,
+    serves_path,
+)
+
+__all__ = [
+    "Serve",
+    "is_valid_slug",
+    "load_serves",
+    "save_serves",
+    "serves_lock_path",
+    "serves_path",
+]

meridian_cli-0.3.32/src/meridian/lib/artifact/_serve_dir.py

@@ -0,0 +1,45 @@
+"""Prefix-aware static server used by detached artifact serves."""
+
+from __future__ import annotations
+
+import sys
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from meridian.lib.artifact.store import is_valid_slug
+
+
+def main() -> None:
+    """Serve a directory under one URL path prefix."""
+    if len(sys.argv) != 4:
+        raise SystemExit("usage: _serve_dir DIRECTORY PORT SLUG")
+    directory = Path(sys.argv[1])
+    try:
+        port = int(sys.argv[2])
+    except ValueError as exc:
+        raise SystemExit("port must be an integer") from exc
+    slug = sys.argv[3]
+    if not directory.is_dir():
+        raise SystemExit(f"not a directory: {directory}")
+    if not 1 <= port <= 65535:
+        raise SystemExit("port must be between 1 and 65535")
+    if not is_valid_slug(slug):
+        raise SystemExit("invalid slug")
+
+    prefix = f"/{slug}"
+
+    class PrefixHandler(SimpleHTTPRequestHandler):
+        def translate_path(self, path: str) -> str:
+            if path == prefix:
+                path = "/"
+            elif path.startswith(f"{prefix}/"):
+                path = path[len(prefix) :]
+            return super().translate_path(path)
+
+    handler = partial(PrefixHandler, directory=str(directory))
+    ThreadingHTTPServer(("127.0.0.1", port), handler).serve_forever()
+
+
+if __name__ == "__main__":
+    main()