@hideandseeklab/aoox 0.1.0-alpha.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.
package/LICENSE ADDED
@@ -0,0 +1,203 @@
1
+ Copyright 2026 hideandseeklab
2
+
3
+ Apache License
4
+ Version 2.0, January 2004
5
+ http://www.apache.org/licenses/
6
+
7
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
8
+
9
+ 1. Definitions.
10
+
11
+ "License" shall mean the terms and conditions for use, reproduction,
12
+ and distribution as defined by Sections 1 through 9 of this document.
13
+
14
+ "Licensor" shall mean the copyright owner or entity authorized by
15
+ the copyright owner that is granting the License.
16
+
17
+ "Legal Entity" shall mean the union of the acting entity and all
18
+ other entities that control, are controlled by, or are under common
19
+ control with that entity. For the purposes of this definition,
20
+ "control" means (i) the power, direct or indirect, to cause the
21
+ direction or management of such entity, whether by contract or
22
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
23
+ outstanding shares, or (iii) beneficial ownership of such entity.
24
+
25
+ "You" (or "Your") shall mean an individual or Legal Entity
26
+ exercising permissions granted by this License.
27
+
28
+ "Source" form shall mean the preferred form for making modifications,
29
+ including but not limited to software source code, documentation
30
+ source, and configuration files.
31
+
32
+ "Object" form shall mean any form resulting from mechanical
33
+ transformation or translation of a Source form, including but
34
+ not limited to compiled object code, generated documentation,
35
+ and conversions to other media types.
36
+
37
+ "Work" shall mean the work of authorship, whether in Source or
38
+ Object form, made available under the License, as indicated by a
39
+ copyright notice that is included in or attached to the work
40
+ (an example is provided in the Appendix below).
41
+
42
+ "Derivative Works" shall mean any work, whether in Source or Object
43
+ form, that is based on (or derived from) the Work and for which the
44
+ editorial revisions, annotations, elaborations, or other modifications
45
+ represent, as a whole, an original work of authorship. For the purposes
46
+ of this License, Derivative Works shall not include works that remain
47
+ separable from, or merely link (or bind by name) to the interfaces of,
48
+ the Work and Derivative Works thereof.
49
+
50
+ "Contribution" shall mean any work of authorship, including
51
+ the original version of the Work and any modifications or additions
52
+ to that Work or Derivative Works thereof, that is intentionally
53
+ submitted to Licensor for inclusion in the Work by the copyright owner
54
+ or by an individual or Legal Entity authorized to submit on behalf of
55
+ the copyright owner. For the purposes of this definition, "submitted"
56
+ means any form of electronic, verbal, or written communication sent
57
+ to the Licensor or its representatives, including but not limited to
58
+ communication on electronic mailing lists, source code control systems,
59
+ and issue tracking systems that are managed by, or on behalf of, the
60
+ Licensor for the purpose of discussing and improving the Work, but
61
+ excluding communication that is conspicuously marked or otherwise
62
+ designated in writing by the copyright owner as "Not a Contribution."
63
+
64
+ "Contributor" shall mean Licensor and any individual or Legal Entity
65
+ on behalf of whom a Contribution has been received by Licensor and
66
+ subsequently incorporated within the Work.
67
+
68
+ 2. Grant of Copyright License. Subject to the terms and conditions of
69
+ this License, each Contributor hereby grants to You a perpetual,
70
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
71
+ copyright license to reproduce, prepare Derivative Works of,
72
+ publicly display, publicly perform, sublicense, and distribute the
73
+ Work and such Derivative Works in Source or Object form.
74
+
75
+ 3. Grant of Patent License. Subject to the terms and conditions of
76
+ this License, each Contributor hereby grants to You a perpetual,
77
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
78
+ (except as stated in this section) patent license to make, have made,
79
+ use, offer to sell, sell, import, and otherwise transfer the Work,
80
+ where such license applies only to those patent claims licensable
81
+ by such Contributor that are necessarily infringed by their
82
+ Contribution(s) alone or by combination of their Contribution(s)
83
+ with the Work to which such Contribution(s) was submitted. If You
84
+ institute patent litigation against any entity (including a
85
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
86
+ or a Contribution incorporated within the Work constitutes direct
87
+ or contributory patent infringement, then any patent licenses
88
+ granted to You under this License for that Work shall terminate
89
+ as of the date such litigation is filed.
90
+
91
+ 4. Redistribution. You may reproduce and distribute copies of the
92
+ Work or Derivative Works thereof in any medium, with or without
93
+ modifications, and in Source or Object form, provided that You
94
+ meet the following conditions:
95
+
96
+ (a) You must give any other recipients of the Work or
97
+ Derivative Works a copy of this License; and
98
+
99
+ (b) You must cause any modified files to carry prominent notices
100
+ stating that You changed the files; and
101
+
102
+ (c) You must retain, in the Source form of any Derivative Works
103
+ that You distribute, all copyright, patent, trademark, and
104
+ attribution notices from the Source form of the Work,
105
+ excluding those notices that do not pertain to any part of
106
+ the Derivative Works; and
107
+
108
+ (d) If the Work includes a "NOTICE" text file as part of its
109
+ distribution, then any Derivative Works that You distribute must
110
+ include a readable copy of the attribution notices contained
111
+ within such NOTICE file, excluding those notices that do not
112
+ pertain to any part of the Derivative Works, in at least one
113
+ of the following places: within a NOTICE text file distributed
114
+ as part of the Derivative Works; within the Source form or
115
+ documentation, if provided along with the Derivative Works; or,
116
+ within a display generated by the Derivative Works, if and
117
+ wherever such third-party notices normally appear. The contents
118
+ of the NOTICE file are for informational purposes only and
119
+ do not modify the License. You may add Your own attribution
120
+ notices within Derivative Works that You distribute, alongside
121
+ or as an addendum to the NOTICE text from the Work, provided
122
+ that such additional attribution notices cannot be construed
123
+ as modifying the License.
124
+
125
+ You may add Your own copyright statement to Your modifications and
126
+ may provide additional or different license terms and conditions
127
+ for use, reproduction, or distribution of Your modifications, or
128
+ for any such Derivative Works as a whole, provided Your use,
129
+ reproduction, and distribution of the Work otherwise complies with
130
+ the conditions stated in this License.
131
+
132
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
133
+ any Contribution intentionally submitted for inclusion in the Work
134
+ by You to the Licensor shall be under the terms and conditions of
135
+ this License, without any additional terms or conditions.
136
+ Notwithstanding the above, nothing herein shall supersede or modify
137
+ the terms of any separate license agreement you may have executed
138
+ with Licensor regarding such Contributions.
139
+
140
+ 6. Trademarks. This License does not grant permission to use the trade
141
+ names, trademarks, service marks, or product names of the Licensor,
142
+ except as required for reasonable and customary use in describing the
143
+ origin of the Work and reproducing the content of the NOTICE file.
144
+
145
+ 7. Disclaimer of Warranty. Unless required by applicable law or
146
+ agreed to in writing, Licensor provides the Work (and each
147
+ Contributor provides its Contributions) on an "AS IS" BASIS,
148
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
149
+ implied, including, without limitation, any warranties or conditions
150
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
151
+ PARTICULAR PURPOSE. You are solely responsible for determining the
152
+ appropriateness of using or redistributing the Work and assume any
153
+ risks associated with Your exercise of permissions under this License.
154
+
155
+ 8. Limitation of Liability. In no event and under no legal theory,
156
+ whether in tort (including negligence), contract, or otherwise,
157
+ unless required by applicable law (such as deliberate and grossly
158
+ negligent acts) or agreed to in writing, shall any Contributor be
159
+ liable to You for damages, including any direct, indirect, special,
160
+ incidental, or consequential damages of any character arising as a
161
+ result of this License or out of the use or inability to use the
162
+ Work (including but not limited to damages for loss of goodwill,
163
+ work stoppage, computer failure or malfunction, or any and all
164
+ other commercial damages or losses), even if such Contributor
165
+ has been advised of the possibility of such damages.
166
+
167
+ 9. Accepting Warranty or Additional Liability. While redistributing
168
+ the Work or Derivative Works thereof, You may choose to offer,
169
+ and charge a fee for, acceptance of support, warranty, indemnity,
170
+ or other liability obligations and/or rights consistent with this
171
+ License. However, in accepting such obligations, You may act only
172
+ on Your own behalf and on Your sole responsibility, not on behalf
173
+ of any other Contributor, and only if You agree to indemnify,
174
+ defend, and hold each Contributor harmless for any liability
175
+ incurred by, or claims asserted against, such Contributor by reason
176
+ of your accepting any such warranty or additional liability.
177
+
178
+ END OF TERMS AND CONDITIONS
179
+
180
+ APPENDIX: How to apply the Apache License to your work.
181
+
182
+ To apply the Apache License to your work, attach the following
183
+ boilerplate notice, with the fields enclosed by brackets "[]"
184
+ replaced with your own identifying information. (Don't include
185
+ the brackets!) The text should be enclosed in the appropriate
186
+ comment syntax for the file format. We also recommend that a
187
+ file or class name and description of purpose be included on the
188
+ same "printed page" as the copyright notice for easier
189
+ identification within third-party archives.
190
+
191
+ Copyright [yyyy] [name of copyright owner]
192
+
193
+ Licensed under the Apache License, Version 2.0 (the "License");
194
+ you may not use this file except in compliance with the License.
195
+ You may obtain a copy of the License at
196
+
197
+ http://www.apache.org/licenses/LICENSE-2.0
198
+
199
+ Unless required by applicable law or agreed to in writing, software
200
+ distributed under the License is distributed on an "AS IS" BASIS,
201
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
202
+ See the License for the specific language governing permissions and
203
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,384 @@
1
+ aoox
2
+ =================
3
+
4
+ CLI for [aoox](https://github.com/hideandseeklab/aoox-api), a self-hosted PaaS — build and deploy
5
+
6
+
7
+ [![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
8
+ [![Version](https://img.shields.io/npm/v/%40hideandseeklab%2Faoox.svg)](https://npmjs.org/package/@hideandseeklab/aoox)
9
+ [![Downloads/week](https://img.shields.io/npm/dw/%40hideandseeklab%2Faoox.svg)](https://npmjs.org/package/@hideandseeklab/aoox)
10
+
11
+
12
+ <!-- toc -->
13
+ * [Usage](#usage)
14
+ * [Installation](#installation)
15
+ * [Commands](#commands)
16
+ <!-- tocstop -->
17
+ # Usage
18
+ <!-- usage -->
19
+ ```sh-session
20
+ $ npm install -g @hideandseeklab/aoox
21
+ $ aoox COMMAND
22
+ running command...
23
+ $ aoox (--version)
24
+ @hideandseeklab/aoox/0.1.0-alpha.0 win32-x64 node-v24.12.0
25
+ $ aoox --help [COMMAND]
26
+ USAGE
27
+ $ aoox COMMAND
28
+ ...
29
+ ```
30
+ <!-- usagestop -->
31
+
32
+ # Installation
33
+
34
+ `aoox` is still in **alpha** — published to npm under the `alpha` dist-tag, not `latest`
35
+ (the package has never had a stable release, so `npm install -g @hideandseeklab/aoox` without a
36
+ tag will fail to find a version). Install explicitly with this tag:
37
+
38
+ ```sh-session
39
+ npm install -g @hideandseeklab/aoox@alpha
40
+ ```
41
+
42
+ `aoox` is then available globally. This also applies to `aoox install` on a new VPS —
43
+ Node ≥22 must already be installed on that VPS **before** the step above (`aoox install`
44
+ itself needs Node to run, so it cannot install Node for you first).
45
+
46
+ To install from source (e.g. to contribute, or to get the latest `main` before it is
47
+ released to npm):
48
+
49
+ ```sh-session
50
+ git clone https://github.com/hideandseeklab/aoox-cli.git
51
+ cd aoox-cli
52
+ npm install
53
+ npm run build
54
+ npm link # or: npm install -g .
55
+ ```
56
+
57
+ # Commands
58
+ <!-- commands -->
59
+ * [`aoox help [COMMAND]`](#aoox-help-command)
60
+ * [`aoox plugins`](#aoox-plugins)
61
+ * [`aoox plugins add PLUGIN`](#aoox-plugins-add-plugin)
62
+ * [`aoox plugins:inspect PLUGIN...`](#aoox-pluginsinspect-plugin)
63
+ * [`aoox plugins install PLUGIN`](#aoox-plugins-install-plugin)
64
+ * [`aoox plugins link PATH`](#aoox-plugins-link-path)
65
+ * [`aoox plugins remove [PLUGIN]`](#aoox-plugins-remove-plugin)
66
+ * [`aoox plugins reset`](#aoox-plugins-reset)
67
+ * [`aoox plugins uninstall [PLUGIN]`](#aoox-plugins-uninstall-plugin)
68
+ * [`aoox plugins unlink [PLUGIN]`](#aoox-plugins-unlink-plugin)
69
+ * [`aoox plugins update`](#aoox-plugins-update)
70
+
71
+ ## `aoox help [COMMAND]`
72
+
73
+ Display help for aoox.
74
+
75
+ ```
76
+ USAGE
77
+ $ aoox help [COMMAND...] [-n]
78
+
79
+ ARGUMENTS
80
+ [COMMAND...] Command to show help for.
81
+
82
+ FLAGS
83
+ -n, --nested-commands Include all nested commands in the output.
84
+
85
+ DESCRIPTION
86
+ Display help for aoox.
87
+ ```
88
+
89
+ _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/6.3.0/src/commands/help.ts)_
90
+
91
+ ## `aoox plugins`
92
+
93
+ List installed plugins.
94
+
95
+ ```
96
+ USAGE
97
+ $ aoox plugins [--json] [--core]
98
+
99
+ FLAGS
100
+ --core Show core plugins.
101
+
102
+ GLOBAL FLAGS
103
+ --json Format output as json.
104
+
105
+ DESCRIPTION
106
+ List installed plugins.
107
+
108
+ EXAMPLES
109
+ $ aoox plugins
110
+ ```
111
+
112
+ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.5.2/src/commands/plugins/index.ts)_
113
+
114
+ ## `aoox plugins add PLUGIN`
115
+
116
+ Installs a plugin into aoox.
117
+
118
+ ```
119
+ USAGE
120
+ $ aoox plugins add PLUGIN... [--json] [-f] [-h] [-s | -v]
121
+
122
+ ARGUMENTS
123
+ PLUGIN... Plugin to install.
124
+
125
+ FLAGS
126
+ -f, --force Force npm to fetch remote resources even if a local copy exists on disk.
127
+ -h, --help Show CLI help.
128
+ -s, --silent Silences npm output.
129
+ -v, --verbose Show verbose npm output.
130
+
131
+ GLOBAL FLAGS
132
+ --json Format output as json.
133
+
134
+ DESCRIPTION
135
+ Installs a plugin into aoox.
136
+
137
+ Uses npm to install plugins.
138
+
139
+ Installation of a user-installed plugin will override a core plugin.
140
+
141
+ Use the AOOX_NPM_LOG_LEVEL environment variable to set the npm loglevel.
142
+ Use the AOOX_NPM_REGISTRY environment variable to set the npm registry.
143
+
144
+ ALIASES
145
+ $ aoox plugins add
146
+
147
+ EXAMPLES
148
+ Install a plugin from npm registry.
149
+
150
+ $ aoox plugins add myplugin
151
+
152
+ Install a plugin from a github url.
153
+
154
+ $ aoox plugins add https://github.com/someuser/someplugin
155
+
156
+ Install a plugin from a github slug.
157
+
158
+ $ aoox plugins add someuser/someplugin
159
+ ```
160
+
161
+ ## `aoox plugins:inspect PLUGIN...`
162
+
163
+ Displays installation properties of a plugin.
164
+
165
+ ```
166
+ USAGE
167
+ $ aoox plugins inspect PLUGIN...
168
+
169
+ ARGUMENTS
170
+ PLUGIN... [default: .] Plugin to inspect.
171
+
172
+ FLAGS
173
+ -h, --help Show CLI help.
174
+ -v, --verbose
175
+
176
+ GLOBAL FLAGS
177
+ --json Format output as json.
178
+
179
+ DESCRIPTION
180
+ Displays installation properties of a plugin.
181
+
182
+ EXAMPLES
183
+ $ aoox plugins inspect myplugin
184
+ ```
185
+
186
+ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.5.2/src/commands/plugins/inspect.ts)_
187
+
188
+ ## `aoox plugins install PLUGIN`
189
+
190
+ Installs a plugin into aoox.
191
+
192
+ ```
193
+ USAGE
194
+ $ aoox plugins install PLUGIN... [--json] [-f] [-h] [-s | -v]
195
+
196
+ ARGUMENTS
197
+ PLUGIN... Plugin to install.
198
+
199
+ FLAGS
200
+ -f, --force Force npm to fetch remote resources even if a local copy exists on disk.
201
+ -h, --help Show CLI help.
202
+ -s, --silent Silences npm output.
203
+ -v, --verbose Show verbose npm output.
204
+
205
+ GLOBAL FLAGS
206
+ --json Format output as json.
207
+
208
+ DESCRIPTION
209
+ Installs a plugin into aoox.
210
+
211
+ Uses npm to install plugins.
212
+
213
+ Installation of a user-installed plugin will override a core plugin.
214
+
215
+ Use the AOOX_NPM_LOG_LEVEL environment variable to set the npm loglevel.
216
+ Use the AOOX_NPM_REGISTRY environment variable to set the npm registry.
217
+
218
+ ALIASES
219
+ $ aoox plugins add
220
+
221
+ EXAMPLES
222
+ Install a plugin from npm registry.
223
+
224
+ $ aoox plugins install myplugin
225
+
226
+ Install a plugin from a github url.
227
+
228
+ $ aoox plugins install https://github.com/someuser/someplugin
229
+
230
+ Install a plugin from a github slug.
231
+
232
+ $ aoox plugins install someuser/someplugin
233
+ ```
234
+
235
+ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.5.2/src/commands/plugins/install.ts)_
236
+
237
+ ## `aoox plugins link PATH`
238
+
239
+ Links a plugin into the CLI for development.
240
+
241
+ ```
242
+ USAGE
243
+ $ aoox plugins link PATH [-h] [--install] [-v]
244
+
245
+ ARGUMENTS
246
+ PATH [default: .] path to plugin
247
+
248
+ FLAGS
249
+ -h, --help Show CLI help.
250
+ -v, --verbose
251
+ --[no-]install Install dependencies after linking the plugin.
252
+
253
+ DESCRIPTION
254
+ Links a plugin into the CLI for development.
255
+
256
+ Installation of a linked plugin will override a user-installed or core plugin.
257
+
258
+ e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
259
+ command will override the user-installed or core plugin implementation. This is useful for development work.
260
+
261
+
262
+ EXAMPLES
263
+ $ aoox plugins link myplugin
264
+ ```
265
+
266
+ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.5.2/src/commands/plugins/link.ts)_
267
+
268
+ ## `aoox plugins remove [PLUGIN]`
269
+
270
+ Removes a plugin from the CLI.
271
+
272
+ ```
273
+ USAGE
274
+ $ aoox plugins remove [PLUGIN...] [-h] [-v]
275
+
276
+ ARGUMENTS
277
+ [PLUGIN...] plugin to uninstall
278
+
279
+ FLAGS
280
+ -h, --help Show CLI help.
281
+ -v, --verbose
282
+
283
+ DESCRIPTION
284
+ Removes a plugin from the CLI.
285
+
286
+ ALIASES
287
+ $ aoox plugins unlink
288
+ $ aoox plugins remove
289
+
290
+ EXAMPLES
291
+ $ aoox plugins remove myplugin
292
+ ```
293
+
294
+ ## `aoox plugins reset`
295
+
296
+ Remove all user-installed and linked plugins.
297
+
298
+ ```
299
+ USAGE
300
+ $ aoox plugins reset [--hard] [--reinstall]
301
+
302
+ FLAGS
303
+ --hard Delete node_modules and package manager related files in addition to uninstalling plugins.
304
+ --reinstall Reinstall all plugins after uninstalling.
305
+ ```
306
+
307
+ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.5.2/src/commands/plugins/reset.ts)_
308
+
309
+ ## `aoox plugins uninstall [PLUGIN]`
310
+
311
+ Removes a plugin from the CLI.
312
+
313
+ ```
314
+ USAGE
315
+ $ aoox plugins uninstall [PLUGIN...] [-h] [-v]
316
+
317
+ ARGUMENTS
318
+ [PLUGIN...] plugin to uninstall
319
+
320
+ FLAGS
321
+ -h, --help Show CLI help.
322
+ -v, --verbose
323
+
324
+ DESCRIPTION
325
+ Removes a plugin from the CLI.
326
+
327
+ ALIASES
328
+ $ aoox plugins unlink
329
+ $ aoox plugins remove
330
+
331
+ EXAMPLES
332
+ $ aoox plugins uninstall myplugin
333
+ ```
334
+
335
+ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.5.2/src/commands/plugins/uninstall.ts)_
336
+
337
+ ## `aoox plugins unlink [PLUGIN]`
338
+
339
+ Removes a plugin from the CLI.
340
+
341
+ ```
342
+ USAGE
343
+ $ aoox plugins unlink [PLUGIN...] [-h] [-v]
344
+
345
+ ARGUMENTS
346
+ [PLUGIN...] plugin to uninstall
347
+
348
+ FLAGS
349
+ -h, --help Show CLI help.
350
+ -v, --verbose
351
+
352
+ DESCRIPTION
353
+ Removes a plugin from the CLI.
354
+
355
+ ALIASES
356
+ $ aoox plugins unlink
357
+ $ aoox plugins remove
358
+
359
+ EXAMPLES
360
+ $ aoox plugins unlink myplugin
361
+ ```
362
+
363
+ ## `aoox plugins update`
364
+
365
+ Update installed plugins.
366
+
367
+ ```
368
+ USAGE
369
+ $ aoox plugins update [-h] [-v]
370
+
371
+ FLAGS
372
+ -h, --help Show CLI help.
373
+ -v, --verbose
374
+
375
+ DESCRIPTION
376
+ Update installed plugins.
377
+ ```
378
+
379
+ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.5.2/src/commands/plugins/update.ts)_
380
+ <!-- commandsstop -->
381
+
382
+ ## Versioning
383
+
384
+ Versioned independently from `aoox-api`, `aoox-web`, and `aoox-landing` — see [CHANGELOG.md](CHANGELOG.md).
@@ -0,0 +1,10 @@
1
+ # `aoox install` assets
2
+
3
+ Copies of `aoox-api`'s distribution compose files, bundled here so
4
+ `aoox install` works on a bare VPS without any network access to that repo.
5
+
6
+ - `docker-compose.dist.yml`
7
+ - `docker-compose.domain.yml`
8
+
9
+ **Keep these in sync by hand** when the source files change — there is no
10
+ automated check for drift yet.
@@ -0,0 +1,146 @@
1
+ # Distribution stack: postgres + api + web, using published images.
2
+ #
3
+ # cp .env.dist.example .env.dist # fill in the secrets
4
+ # docker compose -f docker-compose.dist.yml --env-file .env.dist up -d
5
+ #
6
+ # To build the images locally instead (both repos checked out side by side):
7
+ # docker compose -f docker-compose.dist.yml -f docker-compose.build.yml --env-file .env.dist up -d --build
8
+ #
9
+ # First run: open http://localhost:3000 and create the owner account on /setup,
10
+ # or set ADMIN_EMAIL/ADMIN_PASSWORD in .env.dist for non-interactive onboarding.
11
+ #
12
+ # Own domain (https, http redirected) for the panel itself: add the
13
+ # docker-compose.domain.yml override — see its header. Published ports keep
14
+ # working for IP-based access either way.
15
+ #
16
+ # Web terminal: a container cannot open a shell on the host directly, so the
17
+ # API SSHes to it. The API generates its own keypair into
18
+ # ./secrets on first use; Settings -> Terminal shows the one-line command that
19
+ # authorizes it on the host. Set TERMINAL_SSH_USER in .env.dist.
20
+
21
+ name: aoox
22
+
23
+ # The panel's own containers rotate their logs too (same policy as the containers the API starts).
24
+ x-logging: &logging
25
+ driver: json-file
26
+ options:
27
+ max-size: ${CONTAINER_LOG_MAX_SIZE:-10m}
28
+ max-file: "${CONTAINER_LOG_MAX_FILE:-3}"
29
+
30
+ services:
31
+ postgres:
32
+ image: postgres:16-alpine
33
+ restart: unless-stopped
34
+ logging: *logging
35
+ environment:
36
+ POSTGRES_USER: aoox
37
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env.dist}
38
+ POSTGRES_DB: aoox
39
+ volumes:
40
+ - postgres_data:/var/lib/postgresql/data
41
+ healthcheck:
42
+ test: ['CMD-SHELL', 'pg_isready -U aoox -d aoox']
43
+ interval: 5s
44
+ timeout: 3s
45
+ retries: 10
46
+
47
+ api:
48
+ image: ${API_IMAGE:-hideandseeklab/aoox-api:latest}
49
+ restart: unless-stopped
50
+ logging: *logging
51
+ # Node as PID 1 does not reap the shells spawned by the terminal feature.
52
+ init: true
53
+ depends_on:
54
+ postgres:
55
+ condition: service_healthy
56
+ environment:
57
+ NODE_ENV: production
58
+ PORT: 3001
59
+ DB_HOST: postgres
60
+ DB_PORT: 5432
61
+ DB_USERNAME: aoox
62
+ DB_PASSWORD: ${POSTGRES_PASSWORD}
63
+ DB_NAME: aoox
64
+ DB_MIGRATIONS_RUN: 'true'
65
+ JWT_SECRET: ${JWT_SECRET:?set JWT_SECRET in .env.dist (openssl rand -hex 32)}
66
+ JWT_EXPIRES_IN: ${JWT_EXPIRES_IN:-7d}
67
+ WEB_ORIGIN: ${WEB_ORIGIN:-http://localhost:3000}
68
+ ADMIN_EMAIL: ${ADMIN_EMAIL:-}
69
+ ADMIN_PASSWORD: ${ADMIN_PASSWORD:-}
70
+ ADMIN_NAME: ${ADMIN_NAME:-}
71
+ TERMINAL_SSH_HOST: ${TERMINAL_SSH_HOST:-}
72
+ TERMINAL_SSH_PORT: ${TERMINAL_SSH_PORT:-22}
73
+ TERMINAL_SSH_USER: ${TERMINAL_SSH_USER:-}
74
+ TERMINAL_SSH_PRIVATE_KEY_FILE: ${TERMINAL_SSH_PRIVATE_KEY_FILE:-}
75
+ TERMINAL_SSH_KEY_DIR: /run/secrets/aoox
76
+ TERMINAL_SSH_PASSPHRASE: ${TERMINAL_SSH_PASSPHRASE:-}
77
+ TERMINAL_SSH_PASSWORD: ${TERMINAL_SSH_PASSWORD:-}
78
+ ENCRYPTION_KEY: ${ENCRYPTION_KEY:?set ENCRYPTION_KEY in .env.dist (openssl rand -hex 32)}
79
+ # Self-hosted registry container is started by the API on the host engine.
80
+ REGISTRY_PORT: ${REGISTRY_PORT:-5000}
81
+ REGISTRY_PUBLIC_HOST: ${REGISTRY_PUBLIC_HOST:-localhost}
82
+ REGISTRY_INTERNAL_URL: http://host.docker.internal:${REGISTRY_PORT:-5000}
83
+ # Traefik reverse proxy (container started by the API on the host engine)
84
+ PROXY_HTTP_PORT: ${PROXY_HTTP_PORT:-80}
85
+ PROXY_HTTPS_PORT: ${PROXY_HTTPS_PORT:-443}
86
+ PROXY_ACME_EMAIL: ${PROXY_ACME_EMAIL:-}
87
+ PROXY_ACME_STAGING: ${PROXY_ACME_STAGING:-false}
88
+ # Log rotation for containers started by the API (json-file max-size/max-file)
89
+ METRICS_RETENTION_DAYS: ${METRICS_RETENTION_DAYS:-30}
90
+ # Railpack builds (BuildKit container started by the API on the host engine)
91
+ RAILPACK_VERSION: ${RAILPACK_VERSION:-0.39.0}
92
+ BUILDKIT_VERSION: ${BUILDKIT_VERSION:-v0.27.0}
93
+ BUILDKIT_CACHE_KEEP_GB: ${BUILDKIT_CACHE_KEEP_GB:-10}
94
+ CONTAINER_LOG_MAX_SIZE: ${CONTAINER_LOG_MAX_SIZE:-10m}
95
+ CONTAINER_LOG_MAX_FILE: ${CONTAINER_LOG_MAX_FILE:-3}
96
+ # Public IP app domains must point at (DNS check); auto-detected when empty.
97
+ PUBLIC_IP: ${PUBLIC_IP:-}
98
+ STORAGE_PATH: ${STORAGE_PATH:-}
99
+ # The api container runs as the unprivileged `node` user; add the gid that
100
+ # owns the docker socket on the host (stat -c %g /var/run/docker.sock).
101
+ group_add:
102
+ - '${DOCKER_GID:-0}'
103
+ volumes:
104
+ # Auto-generated SSH key for the web terminal (written by uid 1000, the
105
+ # `node` user; chown ./secrets if the API reports EACCES).
106
+ - ./secrets:/run/secrets/aoox
107
+ # Docker engine access: needed to run the registry (and, later, deployments).
108
+ - /var/run/docker.sock:/var/run/docker.sock
109
+ # Lets TERMINAL_SSH_HOST=host.docker.internal work on Linux too.
110
+ extra_hosts:
111
+ - 'host.docker.internal:host-gateway'
112
+ ports:
113
+ - '${API_PORT:-3001}:3001'
114
+ networks:
115
+ - default
116
+ - aoox
117
+
118
+ web:
119
+ image: ${WEB_IMAGE:-hideandseeklab/aoox-web:latest}
120
+ restart: unless-stopped
121
+ logging: *logging
122
+ depends_on:
123
+ - api
124
+ environment:
125
+ # Server-side calls go over the compose network...
126
+ API_URL: http://api:3001
127
+ # ...while the browser (terminal socket) needs the externally reachable URL.
128
+ PUBLIC_API_URL: ${PUBLIC_API_URL:-http://localhost:3001}
129
+ # Session cookie is Secure only when WEB_ORIGIN is https:// (override with COOKIE_SECURE).
130
+ WEB_ORIGIN: ${WEB_ORIGIN:-http://localhost:3000}
131
+ COOKIE_SECURE: ${COOKIE_SECURE:-}
132
+ ports:
133
+ - '${WEB_PORT:-3000}:3000'
134
+ networks:
135
+ - default
136
+ - aoox
137
+
138
+ networks:
139
+ # Shared with the proxy (Traefik reaches web/api by name on it) and every app
140
+ # container. The explicit name matters: without it compose would create
141
+ # "aoox_aoox"; ProxyService.ensureNetwork then finds it existing.
142
+ aoox:
143
+ name: aoox
144
+
145
+ volumes:
146
+ postgres_data:
@@ -0,0 +1,49 @@
1
+ # Override: serve the panel on your own domain through the built-in proxy.
2
+ #
3
+ # 1. DNS: point WEB_DOMAIN and API_DOMAIN at this host.
4
+ # 2. .env.dist: set WEB_DOMAIN, API_DOMAIN, PROXY_ACME_EMAIL, and switch
5
+ # WEB_ORIGIN / PUBLIC_API_URL to the https URLs (see .env.dist.example).
6
+ # 3. docker compose -f docker-compose.dist.yml -f docker-compose.domain.yml --env-file .env.dist up -d
7
+ # 4. Provision the proxy from Settings (if not already). Certificates are
8
+ # issued on first request; http then redirects to https.
9
+ #
10
+ # Labels follow ProxyService.buildLabels (same router shape as app domains).
11
+
12
+ services:
13
+ web:
14
+ labels:
15
+ traefik.enable: 'true'
16
+ traefik.http.services.aoox-web.loadbalancer.server.port: '3000'
17
+ # web: 301 to https (Traefik drops :443 itself)
18
+ traefik.http.routers.aoox-web.rule: Host(`${WEB_DOMAIN:?set WEB_DOMAIN in .env.dist}`)
19
+ traefik.http.routers.aoox-web.entrypoints: web
20
+ traefik.http.routers.aoox-web.service: aoox-web
21
+ traefik.http.routers.aoox-web.middlewares: aoox-web-https@docker
22
+ traefik.http.middlewares.aoox-web-https.redirectscheme.scheme: https
23
+ traefik.http.middlewares.aoox-web-https.redirectscheme.permanent: 'true'
24
+ traefik.http.middlewares.aoox-web-https.redirectscheme.port: '${PROXY_HTTPS_PORT:-443}'
25
+ # websecure: Let's Encrypt via the `le` resolver (needs PROXY_ACME_EMAIL)
26
+ traefik.http.routers.aoox-web-secure.rule: Host(`${WEB_DOMAIN:?set WEB_DOMAIN in .env.dist}`)
27
+ traefik.http.routers.aoox-web-secure.entrypoints: websecure
28
+ traefik.http.routers.aoox-web-secure.service: aoox-web
29
+ traefik.http.routers.aoox-web-secure.tls: 'true'
30
+ traefik.http.routers.aoox-web-secure.tls.certresolver: le
31
+
32
+ api:
33
+ labels:
34
+ traefik.enable: 'true'
35
+ traefik.http.services.aoox-api.loadbalancer.server.port: '3001'
36
+ # web: 301 to https (Traefik drops :443 itself)
37
+ traefik.http.routers.aoox-api.rule: Host(`${API_DOMAIN:?set API_DOMAIN in .env.dist}`)
38
+ traefik.http.routers.aoox-api.entrypoints: web
39
+ traefik.http.routers.aoox-api.service: aoox-api
40
+ traefik.http.routers.aoox-api.middlewares: aoox-api-https@docker
41
+ traefik.http.middlewares.aoox-api-https.redirectscheme.scheme: https
42
+ traefik.http.middlewares.aoox-api-https.redirectscheme.permanent: 'true'
43
+ traefik.http.middlewares.aoox-api-https.redirectscheme.port: '${PROXY_HTTPS_PORT:-443}'
44
+ # websecure: Let's Encrypt via the `le` resolver (needs PROXY_ACME_EMAIL)
45
+ traefik.http.routers.aoox-api-secure.rule: Host(`${API_DOMAIN:?set API_DOMAIN in .env.dist}`)
46
+ traefik.http.routers.aoox-api-secure.entrypoints: websecure
47
+ traefik.http.routers.aoox-api-secure.service: aoox-api
48
+ traefik.http.routers.aoox-api-secure.tls: 'true'
49
+ traefik.http.routers.aoox-api-secure.tls.certresolver: le
package/bin/dev.cmd ADDED
@@ -0,0 +1,3 @@
1
+ @echo off
2
+
3
+ node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*
package/bin/dev.js ADDED
@@ -0,0 +1,15 @@
1
+ #!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
2
+
3
+ // dev.js only ever runs from a checkout (never from the published package),
4
+ // so importing straight from src/ — instead of duplicating
5
+ // windows-exit-fix.ts here — is fine.
6
+ // eslint-disable-next-line n/no-unpublished-import
7
+ import {applyWindowsExitFix} from '../src/lib/windows-exit-fix.js'
8
+
9
+ // Must run before any command (and any fetch()) — see the doc comment on
10
+ // applyWindowsExitFix for why.
11
+ applyWindowsExitFix()
12
+
13
+ const {execute} = await import('@oclif/core')
14
+
15
+ await execute({development: true, dir: import.meta.url})
package/bin/run.cmd ADDED
@@ -0,0 +1,3 @@
1
+ @echo off
2
+
3
+ node "%~dp0\run" %*
package/bin/run.js ADDED
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+
3
+ import {applyWindowsExitFix} from '../dist/lib/windows-exit-fix.js'
4
+
5
+ // Must run before any command (and any fetch()) — see the doc comment on
6
+ // applyWindowsExitFix for why.
7
+ applyWindowsExitFix()
8
+
9
+ const {execute} = await import('@oclif/core')
10
+
11
+ await execute({dir: import.meta.url})
@@ -0,0 +1,4 @@
1
+ {
2
+ "commands": {},
3
+ "version": "0.1.0-alpha.0"
4
+ }
package/package.json ADDED
@@ -0,0 +1,77 @@
1
+ {
2
+ "name": "@hideandseeklab/aoox",
3
+ "description": "aoox CLI — build and deploy",
4
+ "version": "0.1.0-alpha.0",
5
+ "author": "hideandseeklab <hideandseek.developer@gmail.com>",
6
+ "publishConfig": {
7
+ "access": "public"
8
+ },
9
+ "bin": {
10
+ "aoox": "./bin/run.js"
11
+ },
12
+ "bugs": "https://github.com/hideandseeklab/aoox-cli/issues",
13
+ "dependencies": {
14
+ "@inquirer/prompts": "^8.7.2",
15
+ "@oclif/core": "^4",
16
+ "@oclif/plugin-help": "^6",
17
+ "@oclif/plugin-plugins": "^5"
18
+ },
19
+ "devDependencies": {
20
+ "@eslint/compat": "^1",
21
+ "@oclif/prettier-config": "^0.2.1",
22
+ "@oclif/test": "^4",
23
+ "@types/chai": "^4",
24
+ "@types/mocha": "^10",
25
+ "@types/node": "^24.13.6",
26
+ "chai": "^4",
27
+ "eslint": "^9",
28
+ "eslint-config-oclif": "^6",
29
+ "eslint-config-prettier": "^10",
30
+ "mocha": "^11",
31
+ "oclif": "^4",
32
+ "shx": "^0.3.3",
33
+ "ts-node": "^10",
34
+ "typescript": "^5"
35
+ },
36
+ "engines": {
37
+ "node": ">=22.0.0"
38
+ },
39
+ "files": [
40
+ "./assets",
41
+ "./bin",
42
+ "./dist",
43
+ "./oclif.manifest.json"
44
+ ],
45
+ "homepage": "https://github.com/hideandseeklab/aoox-cli",
46
+ "keywords": [
47
+ "oclif"
48
+ ],
49
+ "license": "Apache-2.0",
50
+ "main": "dist/index.js",
51
+ "type": "module",
52
+ "oclif": {
53
+ "bin": "aoox",
54
+ "dirname": "aoox",
55
+ "commands": "./dist/commands",
56
+ "plugins": [
57
+ "@oclif/plugin-help",
58
+ "@oclif/plugin-plugins"
59
+ ],
60
+ "topicSeparator": " "
61
+ },
62
+ "repository": {
63
+ "type": "git",
64
+ "url": "git+https://github.com/hideandseeklab/aoox-cli.git"
65
+ },
66
+ "scripts": {
67
+ "build": "shx rm -rf dist && tsc -b",
68
+ "lint": "eslint --max-warnings=0",
69
+ "postpack": "shx rm -f oclif.manifest.json",
70
+ "posttest": "npm run lint",
71
+ "postversion": "git push && git push --follow-tags",
72
+ "prepack": "oclif manifest && oclif readme",
73
+ "test": "mocha --forbid-only \"test/**/*.test.ts\"",
74
+ "version": "oclif readme && git add README.md"
75
+ },
76
+ "types": "dist/index.d.ts"
77
+ }