server-handbook 0.1.0__py3-none-any.whl

server_handbook/__init__.py

@@ -0,0 +1,3 @@
+"""Server Handbook: durable server context and managed deployment records."""
+
+__version__ = "0.1.0"

server_handbook/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

server_handbook/assets/schemas/service.schema.json

@@ -0,0 +1,391 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:server-handbook:service:1",
+  "title": "Server Handbook service declaration v1",
+  "description": "Portable structural validation. The runtime also checks native absolute paths, configured roots, symlinks, source placement, file contents and HTTP URL semantics.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "id",
+    "name",
+    "kind",
+    "state",
+    "home",
+    "readme"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1
+    },
+    "id": {
+      "$ref": "#/$defs/serviceId"
+    },
+    "name": {
+      "$ref": "#/$defs/shortText"
+    },
+    "kind": {
+      "enum": [
+        "compose",
+        "systemd",
+        "project",
+        "desktop",
+        "toolchain"
+      ]
+    },
+    "state": {
+      "enum": [
+        "prepared",
+        "installed",
+        "deployed",
+        "retired"
+      ]
+    },
+    "home": {
+      "$ref": "#/$defs/absolutePath"
+    },
+    "readme": {
+      "allOf": [
+        {
+          "$ref": "#/$defs/absolutePath"
+        },
+        {
+          "pattern": "\\.[mM][dD]$"
+        }
+      ]
+    },
+    "version": {
+      "$ref": "#/$defs/shortText"
+    },
+    "systemd_units": {
+      "type": "array",
+      "maxItems": 256,
+      "items": {
+        "type": "string",
+        "maxLength": 256,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9@_.:\\\\-]*\\.(service|socket|timer|target|mount|automount|path|slice|scope)$",
+        "not": {
+          "pattern": "\\s"
+        }
+      }
+    },
+    "compose": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "project",
+        "service",
+        "files"
+      ],
+      "properties": {
+        "project": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]{0,62}$",
+          "not": {
+            "pattern": "\\s"
+          }
+        },
+        "service": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$",
+          "not": {
+            "pattern": "\\s"
+          }
+        },
+        "files": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "items": {
+            "$ref": "#/$defs/absolutePath"
+          }
+        }
+      }
+    },
+    "packages": {
+      "$ref": "#/$defs/textArray"
+    },
+    "local_ports": {
+      "type": "array",
+      "maxItems": 256,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "bind",
+          "port",
+          "transport",
+          "purpose"
+        ],
+        "properties": {
+          "bind": {
+            "$ref": "#/$defs/text"
+          },
+          "port": {
+            "$ref": "#/$defs/port"
+          },
+          "transport": {
+            "enum": [
+              "tcp",
+              "udp"
+            ]
+          },
+          "purpose": {
+            "$ref": "#/$defs/text"
+          }
+        }
+      }
+    },
+    "remote_endpoints": {
+      "type": "array",
+      "maxItems": 256,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "direction",
+          "host",
+          "port",
+          "transport",
+          "purpose"
+        ],
+        "properties": {
+          "direction": {
+            "enum": [
+              "inbound",
+              "outbound"
+            ]
+          },
+          "host": {
+            "$ref": "#/$defs/text"
+          },
+          "port": {
+            "$ref": "#/$defs/port"
+          },
+          "transport": {
+            "enum": [
+              "tcp",
+              "udp"
+            ]
+          },
+          "purpose": {
+            "$ref": "#/$defs/text"
+          }
+        }
+      }
+    },
+    "config_paths": {
+      "$ref": "#/$defs/pathArray"
+    },
+    "data_paths": {
+      "$ref": "#/$defs/pathArray"
+    },
+    "secret_refs": {
+      "$ref": "#/$defs/pathArray"
+    },
+    "depends_on": {
+      "type": "array",
+      "maxItems": 256,
+      "items": {
+        "$ref": "#/$defs/serviceId"
+      }
+    },
+    "commands": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Display-only maintenance notes; Server Handbook never executes these strings.",
+      "properties": {
+        "status": {
+          "$ref": "#/$defs/text"
+        },
+        "start": {
+          "$ref": "#/$defs/text"
+        },
+        "stop": {
+          "$ref": "#/$defs/text"
+        },
+        "restart": {
+          "$ref": "#/$defs/text"
+        },
+        "logs": {
+          "$ref": "#/$defs/text"
+        }
+      }
+    },
+    "notes": {
+      "$ref": "#/$defs/textArray"
+    },
+    "evidence": {
+      "$ref": "#/$defs/pathArray"
+    },
+    "checks": {
+      "type": "array",
+      "maxItems": 16,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "type",
+          "url",
+          "expected_status",
+          "timeout_seconds"
+        ],
+        "properties": {
+          "type": {
+            "const": "http"
+          },
+          "url": {
+            "allOf": [
+              {
+                "$ref": "#/$defs/text"
+              }
+            ],
+            "maxLength": 2048,
+            "format": "uri",
+            "pattern": "^[hH][tT][tT][pP][sS]?://",
+            "not": {
+              "anyOf": [
+                {
+                  "pattern": "\\s"
+                },
+                {
+                  "pattern": "^[hH][tT][tT][pP][sS]?://[^/?#]*@"
+                }
+              ]
+            }
+          },
+          "expected_status": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "timeout_seconds": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 30
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "compose"
+          },
+          "state": {
+            "const": "deployed"
+          }
+        },
+        "required": [
+          "kind",
+          "state"
+        ]
+      },
+      "then": {
+        "required": [
+          "compose"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "systemd"
+          },
+          "state": {
+            "const": "deployed"
+          }
+        },
+        "required": [
+          "kind",
+          "state"
+        ]
+      },
+      "then": {
+        "required": [
+          "systemd_units"
+        ],
+        "properties": {
+          "systemd_units": {
+            "minItems": 1
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "text": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "allOf": [
+        {
+          "pattern": "\\S"
+        },
+        {
+          "not": {
+            "pattern": "\u0000"
+          }
+        }
+      ]
+    },
+    "shortText": {
+      "allOf": [
+        {
+          "$ref": "#/$defs/text"
+        }
+      ],
+      "maxLength": 200
+    },
+    "serviceId": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
+      "not": {
+        "pattern": "\\s"
+      }
+    },
+    "absolutePath": {
+      "allOf": [
+        {
+          "$ref": "#/$defs/text"
+        }
+      ],
+      "description": "POSIX, Windows drive, or UNC absolute syntax. Native-platform validation and resolved containment are enforced at runtime.",
+      "anyOf": [
+        {
+          "pattern": "^/"
+        },
+        {
+          "pattern": "^[A-Za-z]:[\\\\/]"
+        },
+        {
+          "pattern": "^\\\\"
+        }
+      ]
+    },
+    "textArray": {
+      "type": "array",
+      "maxItems": 256,
+      "items": {
+        "$ref": "#/$defs/text"
+      }
+    },
+    "pathArray": {
+      "type": "array",
+      "maxItems": 256,
+      "items": {
+        "$ref": "#/$defs/absolutePath"
+      }
+    },
+    "port": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 65535
+    }
+  }
+}

server_handbook/assets/skills/server-handbook/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: server-handbook
+description: Adopt, inspect, deploy, or hand off projects on a server using Server Handbook's registry and managed operation receipts. Use for service maintenance and server context recovery, not unrelated coding tasks.
+---
+
+# Server Handbook
+
+Use the installed CLI or `handbook_*` MCP tools to find the actual service and its maintenance instructions. The user may have chosen custom paths; do not assume `/srv/workspace` or move existing projects.
+
+Start with `handoff` / `handbook_handoff`, then inspect the target service and read its registered README. Read existing workspace and project AGENTS instructions. Preserve explicit user choices and authorization; this skill supplies a workflow, not additional permission.
+
+Treat these as different evidence:
+
+- Declaration: desired metadata, paths and current registry revision.
+- Observation: a fresh query, possibly `unknown` if permissions or tools are unavailable.
+- Receipt: what a specific managed operation actually executed and verified at a recorded time.
+
+For deployment, inspect the plan and source drift first. Apply only the requested registered service action, with its current expected revision and a meaningful purpose. Inspect the resulting receipt. Process readiness alone does not establish business correctness; report the configured check scope and any missing checks.
+
+For metadata changes, edit the service's declared source file, then register it with the current expected revision. Registration and managed execution update their own README block automatically; retain manual notes. Run doctor and inspect reported drift or unfinished operations before reporting completion.
+
+If work was interrupted, inspect its receipt and live state. Recovery only marks abandoned work interrupted; it does not replay commands or roll back external effects. Do not rerun first-time database initialization as routine maintenance.
+
+Read [the workflow reference](references/workflow.md) when preparing a new project, adopting an old one, or handling an incomplete operation. Direct shell actions outside this tool are not fully recorded; explain such changes rather than claiming a complete audit trail.

server_handbook/assets/skills/server-handbook/references/workflow.md

@@ -0,0 +1,39 @@
+# Using the shared server workflow
+
+Commands below assume the workspace config is discoverable. Otherwise add `--config /absolute/path/to/.server-handbook/config.json` before the subcommand. Use `--help` to confirm installed options.
+
+## Locate and inspect
+
+```bash
+server-handbook handoff
+server-handbook list
+server-handbook show SERVICE_ID
+server-handbook doctor
+```
+
+Follow returned README paths and the recorded Compose files or systemd units. `overview --runtime` adds current host observations. Missing permissions return unknown, not stopped. Descriptor `commands` values are reference text and are never an execution mechanism.
+
+## Prepare or adopt
+
+`project new` and `adopt` preview by default. `--apply` writes their reviewed preparation files; neither deploys or registers a service. Adoption retains the existing home and manual documentation. Review discovered candidates before deciding they are current services.
+
+Fill `home/deploy/registry/SERVICE_ID.json` with actual metadata. Keep credentials in their existing controlled configuration, and record only paths in `secret_refs`. State `prepared` remains honest until actual deployment is established. Optional profiles guide development without replacing repository-specific conventions.
+
+## Register and deploy
+
+```bash
+server-handbook register /absolute/service-home/deploy/registry/SERVICE_ID.json --note 'Actual metadata change and known verification scope'
+server-handbook plan SERVICE_ID --action up
+server-handbook apply SERVICE_ID --action up --expect-revision REVISION --note 'Purpose of this authorized deployment'
+server-handbook operations --service SERVICE_ID
+server-handbook operation OPERATION_ID
+server-handbook doctor
+```
+
+On an existing declaration, registration also requires `--expect-revision REVISION`. Resolve conflicts by rereading and comparing; do not overwrite blindly. Compose `up/restart/stop` applies only to the named service; dependencies must already be running. systemd `start/restart/stop/reload` applies to the registered units.
+
+Read the receipt even if the process started. It distinguishes execution failure, check failure, process-only verification, configured HTTP verification, and documentation refresh failure. For business acceptance beyond those probes, use the project's existing tests under the user's task and record the additional outcome honestly in maintenance notes.
+
+## Incomplete work
+
+An unfinished operation blocks another managed action on the same service. Inspect both the receipt and current state. `recover OPERATION_ID --note ...` refuses a live owner and marks abandoned work interrupted. It never performs rollback, retries commands or resets data. Build a new plan only after understanding remaining effects.

server_handbook/cli.py

@@ -0,0 +1,157 @@
+"""One CLI over the shared validation, registration and execution core."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .errors import HandbookError
+
+
+def parser():
+    root = argparse.ArgumentParser(description="Server Handbook: server context, deployment registry, and tracked operations.")
+    root.add_argument("--version", action="version", version=f"Server Handbook {__version__}")
+    root.add_argument("--config", help="Workspace config; also SERVER_HANDBOOK_CONFIG or nearest .server-handbook/config.json")
+    commands = root.add_subparsers(dest="command", required=True)
+    init = commands.add_parser("init", help="Preview initialization; --apply creates only tool-owned files and managed blocks")
+    init.add_argument("--workspace", required=True)
+    init.add_argument("--name", default="Server Handbook")
+    init.add_argument("--project-root", action="append")
+    init.add_argument("--service-root", action="append")
+    init.add_argument("--records-dir")
+    init.add_argument("--apply", action="store_true")
+    project = commands.add_parser("project", help="Prepare a new project without claiming a deployment")
+    new = project.add_subparsers(dest="project_command", required=True).add_parser("new")
+    new.add_argument("id")
+    new.add_argument("--name", required=True)
+    new.add_argument("--kind", choices=("project", "compose", "systemd"), default="project")
+    new.add_argument("--home")
+    new.add_argument("--profile", choices=("generic", "python", "node", "java"), default="generic")
+    new.add_argument("--apply", action="store_true")
+    adopt = commands.add_parser("adopt", help="Prepare an existing project; retain its files and manual notes")
+    for name in ("home", "id", "name"):
+        adopt.add_argument(f"--{name}", required=True)
+    adopt.add_argument("--kind", choices=("project", "compose", "systemd", "desktop", "toolchain"), default="project")
+    adopt.add_argument("--compose-file", action="append")
+    adopt.add_argument("--compose-project")
+    adopt.add_argument("--compose-service")
+    adopt.add_argument("--unit", action="append")
+    adopt.add_argument("--apply", action="store_true")
+    register = commands.add_parser("register", help="Register a reviewed descriptor and refresh its managed README block")
+    register.add_argument("file")
+    register.add_argument("--note", required=True)
+    register.add_argument("--expect-revision", type=int)
+    listed = commands.add_parser("list", help="List registered metadata, not live health")
+    listed.add_argument("--offset", type=int, default=0)
+    listed.add_argument("--limit", type=int, default=20)
+    for name in ("show", "history"):
+        commands.add_parser(name).add_argument("id")
+    commands.add_parser("overview").add_argument("--runtime", action="store_true")
+    commands.add_parser("discover", help="Find candidates read-only; never auto-register")
+    commands.add_parser("doctor", help="Check source drift, registry integrity and unfinished operations").add_argument("--runtime", action="store_true")
+    docs = commands.add_parser("docs")
+    render = docs.add_subparsers(dest="docs_command", required=True).add_parser("render")
+    render.add_argument("id")
+    render.add_argument("--apply", action="store_true")
+    commands.add_parser("handoff", help="Compact zero-context entry with next steps")
+    skill = commands.add_parser("skill", help="Export the bundled portable Agent Skill without changing client settings")
+    export = skill.add_subparsers(dest="skill_command", required=True).add_parser("export")
+    export.add_argument("destination")
+    export.add_argument("--apply", action="store_true")
+    for name in ("plan", "apply"):
+        operation = commands.add_parser(name, help="Plan a registered operation" if name == "plan" else "Execute and record a registered operation")
+        operation.add_argument("id")
+        operation.add_argument("--action", required=True, choices=("up", "start", "restart", "stop", "reload"))
+        if name == "apply":
+            operation.add_argument("--expect-revision", required=True, type=int)
+            operation.add_argument("--note", required=True)
+    operations = commands.add_parser("operations")
+    operations.add_argument("--service")
+    operations.add_argument("--limit", type=int, default=20)
+    commands.add_parser("operation").add_argument("id")
+    recovery = commands.add_parser("recover", help="Mark an abandoned operation interrupted; never replay or roll back commands")
+    recovery.add_argument("id")
+    recovery.add_argument("--note", required=True)
+    commands.add_parser("mcp", help="Serve stdio MCP; readonly unless explicitly enabled").add_argument("--allow-write", action="store_true")
+    return root
+
+
+def dispatch(args):
+    from .config import initialize, load_config
+    if args.command == "init":
+        return initialize(args.workspace, name=args.name, project_roots=args.project_root,
+                          service_roots=args.service_root, records_dir=args.records_dir, apply=args.apply)
+    if args.command == "skill":
+        from .documents import export_skill
+        return export_skill(args.destination, apply=args.apply)
+    config = load_config(args.config)
+    from . import documents, operations, registry, runtime
+    if args.command == "project":
+        return documents.project_new(config, args.id, args.name, kind=args.kind, home=args.home,
+                                     profile=args.profile, apply=args.apply)
+    if args.command == "adopt":
+        return documents.adopt(config, args.home, args.id, args.name, kind=args.kind,
+                               compose_files=args.compose_file, compose_project=args.compose_project,
+                               compose_service=args.compose_service, systemd_units=args.unit, apply=args.apply)
+    if args.command == "register":
+        return documents.register_and_render(config, args.file, args.note, expect_revision=args.expect_revision)
+    if args.command == "list":
+        return registry.list_services(config, offset=args.offset, limit=args.limit)
+    if args.command == "show":
+        return registry.get_service(config, args.id)
+    if args.command == "history":
+        return {"history": registry.service_history(config, args.id)}
+    if args.command == "overview":
+        return runtime.overview(config, include_runtime=args.runtime)
+    if args.command == "discover":
+        return runtime.discover(config)
+    if args.command == "doctor":
+        return runtime.doctor(config, include_runtime=args.runtime)
+    if args.command == "docs":
+        return documents.render_service_docs(config, args.id, apply=args.apply)
+    if args.command == "handoff":
+        return documents.handoff(config)
+    if args.command == "plan":
+        return operations.plan_operation(config, args.id, args.action)
+    if args.command == "apply":
+        return operations.apply_operation(config, args.id, args.action, args.expect_revision, args.note)
+    if args.command == "operations":
+        return {"operations": operations.list_operations(config, service_id=args.service, limit=args.limit)}
+    if args.command == "operation":
+        return operations.get_operation(config, args.id)
+    if args.command == "recover":
+        return operations.recover_operation(config, args.id, args.note)
+    raise HandbookError("Unknown command; use --help.")
+
+
+def main(argv=None):
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "mcp":
+            from .mcp import main as mcp_main
+            values = (["--config", args.config] if args.config else []) + (["--allow-write"] if args.allow_write else [])
+            return mcp_main(values)
+        result = dispatch(args)
+        if result is not None:
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        if args.command == "apply" and result["status"] != "succeeded":
+            return 1
+        if args.command == "doctor" and (not result["valid"] or result["unfinished_operations"]):
+            return 1
+        return 0
+    except ImportError as error:
+        if args.command == "mcp":
+            print("MCP extra is unavailable. Install 'server-handbook[mcp]' in this environment.", file=sys.stderr)
+            return 1
+        raise error
+    except (HandbookError, OSError) as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())