@yunuseon/kayra 0.17.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/README.md +2 -0
  2. package/agent/skills/kayra-release/SKILL.md +6 -1
  3. package/ansible/roles/platform/tasks/main.yml +10 -2
  4. package/cli/dist/clients/api/api.js +6 -4
  5. package/cli/dist/clients/api/auth.js +1 -1
  6. package/cli/dist/clients/api/commands.js +1 -49
  7. package/cli/dist/clients/api/directories.js +1 -1
  8. package/cli/dist/clients/api/discovery.js +1 -1
  9. package/cli/dist/clients/api/{contract.js → openapi.js} +3 -52
  10. package/cli/dist/clients/api/protocol.js +1 -66
  11. package/cli/dist/clients/api/runs.js +1 -1
  12. package/cli/dist/clients/api/start.js +3 -3
  13. package/cli/dist/clients/cli/explain.js +1 -1
  14. package/cli/dist/clients/cli/framed.js +1 -1
  15. package/cli/dist/clients/cli/invocation.js +1 -1
  16. package/cli/dist/clients/cli/parser.js +4 -0
  17. package/cli/dist/clients/cli/questions.js +1 -1
  18. package/cli/dist/clients/cli/status.js +1 -1
  19. package/cli/dist/clients/cli/terminal.js +1 -1
  20. package/cli/dist/clients/cli/text.js +1 -1
  21. package/cli/dist/clients/cli/validate.js +1 -1
  22. package/cli/dist/clients/cli/values.js +1 -1
  23. package/cli/dist/clients/cli/views.js +1 -1
  24. package/cli/dist/clients/mcp/run.js +69 -0
  25. package/cli/dist/clients/mcp/server.js +130 -0
  26. package/cli/dist/clients/mcp/tools.js +101 -0
  27. package/cli/dist/clients/wire/contract.js +53 -0
  28. package/cli/dist/clients/{api → wire}/queries.js +1 -1
  29. package/cli/dist/clients/wire/schemas.js +67 -0
  30. package/cli/dist/clients/wire/words.js +48 -0
  31. package/cli/dist/core/adapters/fs.js +1 -1
  32. package/cli/dist/core/adapters/network.js +1 -1
  33. package/cli/dist/core/adapters/opentofu.js +1 -1
  34. package/cli/dist/core/fleet/brand.js +23 -14
  35. package/cli/dist/core/fleet/docs.js +2 -2
  36. package/cli/dist/core/fleet/load.js +3 -2
  37. package/cli/dist/core/fleet/parse.js +59 -91
  38. package/cli/dist/core/fleet/settings.js +38 -13
  39. package/cli/dist/core/fleet/shape.js +5 -20
  40. package/cli/dist/core/interpreter/events.js +1 -1
  41. package/cli/dist/core/interpreter/loop.js +1 -1
  42. package/cli/dist/core/interpreter/needs.js +1 -1
  43. package/cli/dist/core/interpreter/process.js +2 -2
  44. package/cli/dist/core/interpreter/progress.js +1 -1
  45. package/cli/dist/core/interpreter/pty.js +1 -1
  46. package/cli/dist/core/operations/dispatch.js +2 -2
  47. package/cli/dist/core/plan/model.js +1 -1
  48. package/cli/dist/core/recipes/app-check.js +5 -8
  49. package/cli/dist/core/recipes/apps.js +2 -2
  50. package/cli/dist/core/recipes/backup.js +1 -1
  51. package/cli/dist/core/recipes/certs.js +1 -1
  52. package/cli/dist/core/recipes/doctor.js +1 -1
  53. package/cli/dist/core/recipes/host.js +2 -2
  54. package/cli/dist/core/recipes/ssh.js +2 -2
  55. package/cli/dist/core/recipes/steps.js +2 -2
  56. package/cli/dist/core/status/look.js +1 -1
  57. package/cli/dist/core/text/spans.js +1 -1
  58. package/cli/dist/core/validation/facts.js +3 -2
  59. package/cli/dist/core/validation/findings.js +3 -3
  60. package/cli/dist/deployer/app.js +2 -2
  61. package/cli/dist/deployer/brand.js +1 -1
  62. package/cli/dist/deployer/build/builder.js +2 -2
  63. package/cli/dist/deployer/build/bundle.js +2 -2
  64. package/cli/dist/deployer/build/compose.js +1 -1
  65. package/cli/dist/deployer/cron.js +1 -1
  66. package/cli/dist/deployer/ctl/answers.js +1 -1
  67. package/cli/dist/deployer/deployer.js +7 -11
  68. package/cli/dist/deployer/forges/forge.js +1 -1
  69. package/cli/dist/deployer/forges/forgejo.js +1 -1
  70. package/cli/dist/deployer/forges/github.js +1 -1
  71. package/cli/dist/deployer/forges/gitlab.js +1 -1
  72. package/cli/dist/deployer/forges/issues.js +2 -2
  73. package/cli/dist/deployer/forges/notify.js +2 -2
  74. package/cli/dist/deployer/runs/queue.js +8 -1
  75. package/cli/dist/deployer/runs/records.js +1 -1
  76. package/cli/dist/deployer/runs/run.js +2 -2
  77. package/cli/dist/deployer/runs/store.js +1 -1
  78. package/cli/dist/lib/brand.js +2 -0
  79. package/cli/dist/lib/closest.js +17 -0
  80. package/cli/dist/lib/schema.js +7 -0
  81. package/cli/dist/lib/yaml.js +21 -0
  82. package/cli/dist/main.js +12 -4
  83. package/package.json +3 -1
  84. package/schema/app.json +4 -2
  85. package/schema/server.json +10 -5
  86. package/scripts/agent/guard.sh +28 -6
  87. /package/cli/dist/clients/{api → wire}/contract.gen.js +0 -0
  88. /package/cli/dist/clients/{api → wire}/status.js +0 -0
  89. /package/cli/dist/clients/{api → wire}/validate.js +0 -0
  90. /package/cli/dist/{result.js → lib/result.js} +0 -0
  91. /package/cli/dist/{typed.js → lib/typed.js} +0 -0
@@ -0,0 +1,21 @@
1
+ import { parseDocument } from "yaml";
2
+ import { err, ok } from "./result.js";
3
+ import { typed } from "./typed.js";
4
+ export const mapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? typed(Object.fromEntries(Object.entries(value))) : undefined;
5
+ /** YAML text as a value; a syntax error is a value too, not an exception. */
6
+ export const yamlOf = (text) => {
7
+ const document = parseDocument(text);
8
+ const problem = document.errors.at(0);
9
+ return problem === undefined ? ok(document.toJS()) : err(`is not valid YAML: ${problem.message.split("\n")[0] ?? ""}`);
10
+ };
11
+ /** YAML text as a mapping; empty for an empty file. */
12
+ export const fields = (text) => {
13
+ const parsed = yamlOf(text);
14
+ if (!parsed.ok)
15
+ return parsed;
16
+ const value = parsed.value;
17
+ if (value === null || value === undefined)
18
+ return ok({});
19
+ const result = mapping(value);
20
+ return result === undefined ? err("is not a YAML mapping") : ok(result);
21
+ };
package/cli/dist/main.js CHANGED
@@ -9,10 +9,10 @@ import { fromCommand } from "./clients/cli/invocation.js";
9
9
  import { parser, runOptions } from "./clients/cli/parser.js";
10
10
  import { verbose } from "./core/recipes/steps.js";
11
11
  import { opentofu } from "./core/adapters/opentofu.js";
12
- import { statusJson } from "./clients/api/status.js";
12
+ import { statusJson } from "./clients/wire/status.js";
13
13
  import { statusView } from "./clients/cli/status.js";
14
14
  import { overall } from "./core/validation/findings.js";
15
- import { validateJson } from "./clients/api/validate.js";
15
+ import { validateJson } from "./clients/wire/validate.js";
16
16
  import { validateView } from "./clients/cli/validate.js";
17
17
  import { interpret } from "./core/interpreter/loop.js";
18
18
  import { findFleetRoot, loadFleet } from "./core/fleet/load.js";
@@ -20,9 +20,10 @@ import { operation as describe } from "./core/operations/catalog.js";
20
20
  import { contextFor, hasPlan, planOf, query, serverOf, stream } from "./core/operations/dispatch.js";
21
21
  import { systemBrowser } from "./clients/ui/opener.js";
22
22
  import { serve } from "./serve.js";
23
+ import { serveMcp } from "./clients/mcp/server.js";
23
24
  import { network } from "./core/adapters/network.js";
24
25
  import { render } from "./core/plan/describe.js";
25
- import { err, flatMap, map, ok } from "./result.js";
26
+ import { err, flatMap, map, ok } from "./lib/result.js";
26
27
  import { explain } from "./clients/cli/explain.js";
27
28
  import { draw } from "./clients/cli/views.js";
28
29
  import { bad, muted, strong } from "./core/text/spans.js";
@@ -90,7 +91,14 @@ const short = shortener([
90
91
  [homedir(), "~"],
91
92
  ]);
92
93
  const context = contextFor({ kayra, fleet: fleet, version, here: here.value, network: network(2_000), tofu: opentofu });
93
- if (args.command.name === "serve") {
94
+ if (args.command.name === "mcp") {
95
+ // stdout is the protocol: nothing else may write there, and every step's output is piped.
96
+ if (!found.ok)
97
+ fail(found.error);
98
+ else
99
+ serveMcp({ context, short }, (message) => { process.stderr.write(`kayra mcp: ${message}\n`); });
100
+ }
101
+ else if (args.command.name === "serve") {
94
102
  if (!found.ok)
95
103
  fail(found.error);
96
104
  // The browser side: web/dist in a checkout, cli/dist/browser in the package.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yunuseon/kayra",
3
- "version": "0.17.1",
3
+ "version": "0.18.0",
4
4
  "description": "A self-hosted app platform and the CLI that runs it: Traefik, Authelia, a registry, rootless BuildKit and a small deployer per server, set up with OpenTofu and Ansible.",
5
5
  "license": "MIT",
6
6
  "author": "Yunus Öztürk",
@@ -44,6 +44,7 @@
44
44
  "signatures": "rm -rf .cache/signatures && tsc -p cli/tsconfig.build.json --declaration --emitDeclarationOnly --outDir .cache/signatures"
45
45
  },
46
46
  "dependencies": {
47
+ "@modelcontextprotocol/server": "2.3.1",
47
48
  "@optique/core": "1.3.3",
48
49
  "@optique/run": "1.3.3",
49
50
  "yaml": "2.9.1",
@@ -51,6 +52,7 @@
51
52
  },
52
53
  "devDependencies": {
53
54
  "@eslint/js": "10.0.1",
55
+ "@modelcontextprotocol/client": "2.3.1",
54
56
  "@tsconfig/node24": "24.0.5",
55
57
  "@tsconfig/strictest": "2.0.8",
56
58
  "@types/node": "24.19.1",
package/schema/app.json CHANGED
@@ -3,8 +3,9 @@
3
3
  "type": "object",
4
4
  "properties": {
5
5
  "name": {
6
+ "description": "The app's name, as in the server.yml entry.",
6
7
  "type": "string",
7
- "description": "The app's name, as in the server.yml entry."
8
+ "pattern": "^[a-z][a-z0-9-]*$"
8
9
  },
9
10
  "compose": {
10
11
  "type": "array",
@@ -16,7 +17,8 @@
16
17
  "subdomains": {
17
18
  "type": "array",
18
19
  "items": {
19
- "type": "string"
20
+ "type": "string",
21
+ "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
20
22
  },
21
23
  "description": "Hostnames the app claims: <sub>.<domain>."
22
24
  },
@@ -3,6 +3,7 @@
3
3
  "type": "object",
4
4
  "properties": {
5
5
  "kind": {
6
+ "default": "platform",
6
7
  "description": "Which playbook: platform (default; Traefik, Authelia, the deployer, apps), edge or nas.",
7
8
  "type": "string",
8
9
  "enum": [
@@ -14,17 +15,19 @@
14
15
  "target": {
15
16
  "type": "string",
16
17
  "enum": [
17
- "hetzner",
18
18
  "multipass",
19
+ "hetzner",
19
20
  "home"
20
21
  ],
21
22
  "description": "Where it runs: hetzner, multipass (a local VM) or home (a machine nothing creates)."
22
23
  },
23
24
  "domain": {
25
+ "description": "The server's domain; platform subdomains and the apps' hang off it.",
24
26
  "type": "string",
25
- "description": "The server's domain; platform subdomains and the apps' hang off it."
27
+ "pattern": "^([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*$"
26
28
  },
27
29
  "vault": {
30
+ "default": false,
28
31
  "description": "secrets.yml is vault-encrypted (required outside multipass).",
29
32
  "type": "boolean"
30
33
  },
@@ -39,11 +42,12 @@
39
42
  "type": "object",
40
43
  "properties": {
41
44
  "name": {
42
- "type": "string"
45
+ "type": "string",
46
+ "pattern": "^[a-z][a-z0-9-]*$"
43
47
  },
44
48
  "repo": {
45
- "type": "string",
46
- "description": "The app's repository, https://."
49
+ "description": "The app's repository, https://.",
50
+ "type": "string"
47
51
  },
48
52
  "ref": {
49
53
  "description": "The branch to build and deploy (default main).",
@@ -51,6 +55,7 @@
51
55
  },
52
56
  "path": {
53
57
  "description": "The app's root inside the repository (default .).",
58
+ "default": ".",
54
59
  "type": "string"
55
60
  }
56
61
  },
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env bash
2
2
  # =============================================================================
3
- # guard.sh — Claude Code's PreToolUse hook on Bash, in kayra and every fleet
3
+ # guard.sh — Claude Code's PreToolUse hook on Bash and kayra's MCP tools, in kayra and every fleet
4
4
  # (.claude/settings.json): an AI agent may build, test and read freely, but a
5
5
  # command that changes something real waits for the operator to approve it,
6
6
  # in that moment.
@@ -21,6 +21,10 @@
21
21
  # - git push of main or a tag, a force push, deleting a remote branch
22
22
  # - tofu / terraform apply, destroy, import, state changes
23
23
  # - destructive commands over SSH (rm, docker rm/stop/prune/down, systemctl…)
24
+ # kayra's MCP tools (mcp__kayra__<tool>, the fleet's .mcp.json naming the
25
+ # server kayra) the same way, read from their JSON input: a tool that changes
26
+ # a server asks unless dryRun is set or the server is a multipass one; one
27
+ # that changes nothing passes.
24
28
  # Anything else: no output, the normal permission flow.
25
29
  #
26
30
  # It reads the command's text, so it stops mistakes and instructions smuggled
@@ -30,8 +34,6 @@
30
34
  set -uo pipefail
31
35
 
32
36
  input="$(cat)"
33
- command="$(jq -r '.tool_input.command // empty' <<< "$input" 2>/dev/null)"
34
- [ -n "$command" ] || exit 0
35
37
  mode="$(jq -r '.permission_mode // empty' <<< "$input" 2>/dev/null)"
36
38
  project="${CLAUDE_PROJECT_DIR:-$PWD}"
37
39
 
@@ -44,6 +46,28 @@ ask() {
44
46
  '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: $decision, permissionDecisionReason: $reason}}'
45
47
  exit 0
46
48
  }
49
+ # The target a server's server.yml names, if the server is one of this project's.
50
+ target_of() {
51
+ [[ "$1" =~ ^[a-z0-9][a-z0-9-]*$ ]] && [ -f "${project}/servers/$1/server.yml" ] || return 0
52
+ sed -n 's/^target: *\([a-z]*\).*/\1/p' "${project}/servers/$1/server.yml"
53
+ }
54
+
55
+ # ── kayra's MCP tools ───────────────────────────────────────────────────────
56
+ # The tools that change nothing (the catalog's effect "reads"; a test holds this list to it).
57
+ mcp_reads='status|validate|verify|plan|doctor|version|app_check|app_runs|app_log|app_releases'
58
+ tool="$(jq -r '.tool_name // empty' <<< "$input" 2>/dev/null)"
59
+ if [[ "$tool" == mcp__kayra__* ]]; then
60
+ name="${tool#mcp__kayra__}"
61
+ [[ "$name" =~ ^(${mcp_reads})$ ]] && exit 0
62
+ [ "$(jq -r '.tool_input.dryRun // false' <<< "$input" 2>/dev/null)" = true ] && exit 0
63
+ server="$(jq -r '.tool_input.server // empty | strings' <<< "$input" 2>/dev/null)"
64
+ target="$(target_of "$server")"
65
+ [ "$target" = multipass ] || ask "kayra (MCP) ${name} changes ${server:-this machine}${target:+ (target ${target})}"
66
+ exit 0
67
+ fi
68
+
69
+ command="$(jq -r '.tool_input.command // empty' <<< "$input" 2>/dev/null)"
70
+ [ -n "$command" ] || exit 0
47
71
  has() { grep -qE -- "$1" <<< "$command"; }
48
72
 
49
73
  # ── kayra changing a server ─────────────────────────────────────────────────
@@ -52,9 +76,7 @@ verbs='(up|provision|setup|deploy|apps|adopt|down|hosts|job|app (purge|deploy|ro
52
76
  if has "${kayra} +(--[a-z-]+ +)*${verbs}( |$)" && ! has '--dry-run'; then
53
77
  # The server: the word after the verb (after the app subcommand for app …).
54
78
  server="$(grep -oE -- "${kayra} +(--[a-z-]+ +)*${verbs} +[a-z0-9][a-z0-9-]*" <<< "$command" | head -1 | awk '{print $NF}')"
55
- target=""
56
- [ -z "$server" ] || [ ! -f "${project}/servers/${server}/server.yml" ] \
57
- || target="$(sed -n 's/^target: *\([a-z]*\).*/\1/p' "${project}/servers/${server}/server.yml")"
79
+ target="$(target_of "$server")"
58
80
  [ "$target" = multipass ] || ask "kayra changes ${server:-a server}${target:+ (target ${target})}"
59
81
  fi
60
82
  # kayra serve runs any command on any server from a browser, where this guard sees none of them.
File without changes
File without changes
File without changes
File without changes
File without changes