kylrix/ota.yaml at master · Kylrix/kylrix · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
version: 1

project:
  name: kylrix
  description: Kylrix contributor verification and development contract

execution:
  default_context: host
  lifecycle: persistent
  backends:
    container:
      image: node@sha256:a25c9934ff6382cd4f08b6bc26c82bf4ea69b1e6f8dabfb2ead457374127c365
      engines: [docker]
      resources:
        memory:
          minimum: 3GiB
          default: 4GiB
  contexts:
    host:
      backend: native
    contributor:container:
      backend: container
      lifecycle: persistent
      attachments:
        isolated_paths: [node_modules, .next, .pnpm-store]

toolchains:
  node:
    version: ">=22"
    package_managers:
      pnpm: ">=11.5.1"
    fulfillment:
      source: corepack
      mode: run

surfaces:
  contributor:web:
    kind: http
    port: 3005
    path: /
    readiness:
      kind: http
      method: GET
      path: /?stay=1
      headers:
        Accept: text/html
      success:
        status: [200]
      body:
        contains: "<!DOCTYPE html>"
      interval: 5s
      timeout: 3s
      retries: 12
      start_period: 10s
  selfhost:web:
    kind: https
    port: 443
    path: /
    readiness:
      kind: tcp
      interval: 5s
      timeout: 3s
      retries: 60
      start_period: 30s

tasks:
  setup:
    context: host
    description: Materialize local env profile and hydrate pinned pnpm dependencies
    category: setup
    prepare:
      kind: sequence
      steps:
        - kind: ensure_env_file
          path: .env
          template: env.sample
          vars:
            PORT:
              value: "3005"
              mode: replace
            DOMAIN:
              value: localhost
              mode: replace
            NEXT_PUBLIC_APP_URL:
              value: http://localhost:3005
              mode: replace
            NEXT_PUBLIC_APP_URI:
              value: http://localhost:3005
              mode: replace
            NEXT_PUBLIC_ORIGIN:
              value: http://localhost:3005
              mode: replace
            SELFHOST_MODE:
              value: "true"
              mode: replace
            APPWRITE_ENDPOINT:
              value: http://127.0.0.1/v1
              mode: replace
            NEXT_PUBLIC_APPWRITE_ENDPOINT:
              value: http://127.0.0.1/v1
              mode: replace
            APPWRITE_PROJECT_ID:
              value: kylrix-local
              mode: replace
            NEXT_PUBLIC_APPWRITE_PROJECT_ID:
              value: kylrix-local
              mode: replace
            KYLRIX_INTERNAL_JOBS_SECRET:
              random:
                bytes: 32
                encoding: hex
            ATTACHMENT_URL_SIGNING_SECRET:
              random:
                bytes: 32
                encoding: hex
        - kind: dependency_hydration
          medium: package_dependencies
          source:
            kind: node_package_manager
            cwd: .
            manager: pnpm
            mode: install
            frozen_lockfile: true
    requirements:
      toolchains:
        - node
    effects:
      writes: [.env, node_modules, .pnpm-store]
      network: true
      network_kind: dependency_hydration
    safe_for_agent: true
    execution:
      modes:
        container:
          context: contributor:container

  test:
    context: host
    description: Run the repository unit and integration test suite
    command:
      exe: pnpm
      args: [test]
    env_files: [.env]
    depends_on: [setup]
    requirements:
      toolchains:
        - node
    safe_for_agent: true
    execution:
      modes:
        container:
          context: contributor:container

  lint:
    context: host
    description: Run the repository ESLint verification lane
    command:
      exe: pnpm
      args: [lint]
    env_files: [.env]
    depends_on: [setup]
    requirements:
      toolchains:
        - node
    safe_for_agent: true
    execution:
      modes:
        container:
          context: contributor:container

  build:
    context: host
    description: Build the Next.js application
    command:
      exe: pnpm
      args: [build]
    env_files: [.env]
    depends_on: [setup]
    requirements:
      toolchains:
        - node
    effects:
      writes: [.next]
    safe_for_agent: true
    execution:
      modes:
        container:
          context: contributor:container

  verify:
    description: Run the complete finite test, lint, and build verification surface
    replay_inputs:
      - id: pnpm_lockfile
        kind: static_file
        path: pnpm-lock.yaml
    aggregate:
      tasks: [test, lint, build]
    safe_for_agent: true

  dev:
    context: host
    description: Start Kylrix locally with Next.js Turbopack and RxDB local engine
    launch:
      kind: command
      exe: pnpm
      args: [exec, next, dev, --turbopack]
      runtime_projection:
        listener: contributor:web
        adapter: nextjs
    env_files: [.env]
    depends_on: [setup]
    requirements:
      toolchains:
        - node
    runtime:
      kind: service
      surfaces:
        contributor:web:
          project:
            host:
              primary: true
    execution:
      modes:
        container:
          context: contributor:container
          runtime:
            kind: service
            surfaces:
              contributor:web:
                bind:
                  address: 0.0.0.0

  selfhost:env:
    context: host
    description: Materialize the isolated self-hosted Compose interpolation profile
    notes: |
      Keeps the self-hosted container topology separate from the local `.env`.
      Generated secret values are retained on later runs; Ota never replaces them implicitly.
    action:
      kind: ensure_env_file
      path: .ota/kylrix.selfhost.env
      vars:
        KYLRIX_ENV_FILE:
          value: .ota/kylrix.selfhost.env
          mode: replace
        PORT:
          value: "3005"
          mode: missing
        SELFHOST_MODE:
          value: "true"
          mode: replace
        NEXT_PUBLIC_APP_URL:
          value: http://localhost:3005
          mode: missing
        NEXT_PUBLIC_APP_URI:
          value: http://localhost:3005
          mode: missing
        NEXT_PUBLIC_ORIGIN:
          value: http://localhost:3005
          mode: missing
    effects:
      writes: [.ota/kylrix.selfhost.env]
    safe_for_agent: false

  selfhost:build:
    context: host
    description: Build the documented self-hosted Kylrix production image
    notes: |
      Uses the repository Dockerfile and isolated self-hosted interpolation profile. This is an
      image-build proof only; it does not claim Appwrite schema provisioning or application-level
      functional verification.
    adapter_inputs:
      overlays:
        compose:
          files: [docker-compose.yml]
          env_files: [.ota/kylrix.selfhost.env]
    compose:
      kind: build
      services: [kylrix]
    depends_on: [selfhost:env]
    requirements:
      tools:
        docker: "*"
    effects:
      network: true
      network_kind: container_image_hydration
      external_state: [docker]
    safe_for_agent: false

  selfhost:up:
    context: host
    description: Start the documented full self-hosted Kylrix Compose topology
    notes: |
      Starts Kylrix, Appwrite, MariaDB, Redis, and Caddy through the documented Compose stack.
      This owns container lifecycle only. The interactive setup wizard and Appwrite schema
      provisioning still require explicit operator credentials and remain outside this workflow.
    adapter_inputs:
      overlays:
        compose:
          files: [docker-compose.yml]
          env_files: [.ota/kylrix.selfhost.env]
    launch:
      kind: compose
      action: up
      detach: true
    runtime:
      kind: service
      surfaces: [selfhost:web]
    depends_on: [selfhost:build]
    requirements:
      tools:
        docker: "*"
    effects:
      network: true
      network_kind: container_image_hydration
      external_state: [docker, appwrite, mariadb, redis, caddy]
    safe_for_agent: false

  selfhost:down:
    context: host
    description: Stop the self-hosted Compose topology without deleting persistent volumes
    adapter_inputs:
      overlays:
        compose:
          files: [docker-compose.yml]
          env_files: [.ota/kylrix.selfhost.env]
    compose:
      kind: down
    requirements:
      tools:
        docker: "*"
    effects:
      external_state: [docker]
    safe_for_agent: false

workflows:
  default: dev
  dev:
    intent: local_development
    description: Prepare the local environment and start the Next.js Turbopack runtime
    readiness:
      surfaces: [contributor:web]
    setup:
      task: setup
    run:
      task: dev
  verify:
    intent: verification
    description: Run the finite test, lint, and build verification surface
    setup:
      task: setup
    run:
      task: verify
  selfhost:
    intent: production_runtime
    description: Build and start the documented self-hosted Compose topology
    setup:
      task: selfhost:env
    run:
      task: selfhost:up

agent:
  bootstrap:
    ota:
      note: Only install Ota if it is missing and installation is approved.
      source:
        kind: version
        version: v1.6.25
  entrypoint: setup
  default_task: verify
  safe_tasks: [setup, test, lint, build, verify]
  verify_after_changes: [verify]
  refusal_canaries:
    - task: selfhost:up
    - workflow: selfhost
  writable_paths:
    - .env
    - .next
    - app
    - components
    - constants
    - context
    - docs
    - functions
    - hooks
    - lib
    - public
    - scripts
    - theme
    - types
    - utils
    - node_modules
    - .pnpm-store
  exceptions:
    sensitive_writes: [.env]
  protected_paths:
    - .ota/pressure-replay-policy.yaml
    - .github/workflows
    - AGENTS.md
    - docker-compose.app-only.yml
    - docker-compose.yml
    - env.sample
    - ota.yaml
    - package.json
    - pnpm-lock.yaml
  notes: |
    Start with `ota validate`, then `ota doctor`, then `ota tasks --use`.
    Use `ota up --workflow verify --agent` for the finite verification path.
    Use `ota up --workflow dev` for local development.
    Use `ota up --workflow selfhost` for the documented full Compose topology.