Skip to content

Commit e7ba81a

Browse files
3m1n3nc33m1n3nc3
committed
feat: initialize H3 application structure with core components, routing, and middleware
- Added Application class to manage H3 app lifecycle and routing. - Created bootstrap file to initialize application and middleware. - Implemented UserFactory for user model data generation. - Added migrations for users, personal access tokens, user two factors, and notifications tables. - Developed seeders for populating initial user data. - Defined environment types for configuration. - Created a welcome view with a responsive design. - Set up API and web routes with basic responses. - Implemented server entry point to boot application. - Configured TypeScript settings and build process. - Added basic tests for application functionality and decorators.
1 parent 3b491cb commit e7ba81a

99 files changed

Lines changed: 667 additions & 267 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Arkstack Agent Workflows
2+
3+
This file describes higher-order workflows for AI agents working inside Arkstack projects. It composes the lower-level capabilities documented in `SKILLS.md`.
4+
5+
Agents should read `SKILLS.md` first, then use this file to plan multi-step work.
6+
7+
## Operating Principles
8+
9+
- Work from the project root.
10+
- Inspect `package.json`, lockfiles, runtime dependencies, route files, and nearby source before changing code.
11+
- Prefer Arkstack CLI generators for controllers, resources, models, migrations, views, and commands.
12+
- Keep application logic runtime-agnostic unless the task is specifically about Express, H3, or another driver.
13+
- Verify with the narrowest command that gives useful confidence.
14+
- Ask before destructive operations.
15+
16+
## Add an API Endpoint
17+
18+
1. Inspect existing routes under `src/routes`.
19+
2. Run `pnpm ark route:list` if the app can boot.
20+
3. Generate missing pieces:
21+
- `pnpm ark make:controller <Name> --api`
22+
- `pnpm ark make:resource resource <Name>` when shaping a single response.
23+
- `pnpm ark make:resource collection <Name>Collection` when returning lists.
24+
- `pnpm ark make:full-resource <Name> --model <Model>` for a complete CRUD-style surface.
25+
4. Register or update routes in the appropriate route file.
26+
5. Put business logic in services or framework-neutral modules when the endpoint is not trivial.
27+
6. Add or update tests.
28+
7. Verify with `pnpm test` and `pnpm ark route:list`.
29+
30+
## Add a Database-Backed Feature
31+
32+
1. Confirm the project is a full template with Arkormx/database support.
33+
2. Generate model and persistence files:
34+
- `pnpm ark make:model <Name>`
35+
- `pnpm ark make:migration <migration_name>`
36+
- `pnpm ark make:factory <Name>` when tests or seed data need it.
37+
- `pnpm ark make:seeder <Name>` when reusable seed data is needed.
38+
3. Edit the migration and model fields.
39+
4. Add controllers, resources, services, or routes as needed.
40+
5. Run migrations only after confirming the target database is safe.
41+
6. Run `pnpm ark models:sync` when schema-derived model typing should be refreshed.
42+
7. Verify with tests and route inspection.
43+
44+
## Add a View-Rendered Page
45+
46+
1. Inspect existing routes and view naming conventions.
47+
2. Generate the view with `pnpm ark make:view <path-or-name>`.
48+
3. Add or update the controller action that renders the view.
49+
4. Register the route.
50+
5. Keep reusable view data preparation in services or helpers when it grows beyond a simple action.
51+
6. Verify the route list and run tests if the project has HTTP coverage.
52+
53+
## Add Middleware
54+
55+
1. Inspect existing middleware in `src/app/http/middlewares`.
56+
2. Decide whether the middleware is runtime-agnostic or driver-specific.
57+
3. Implement the middleware using the existing driver conventions.
58+
4. Register it where routes or runtime bootstrap expect middleware.
59+
5. Run `pnpm ark route:list` when route-level middleware changes route behavior.
60+
6. Add tests for auth, request mutation, error handling, or response behavior.
61+
62+
## Work on Authentication
63+
64+
1. Inspect the app models for `User`, `PersonalAccessToken`, and two-factor models if present.
65+
2. Inspect auth config, middleware, and existing tests before changing behavior.
66+
3. Keep session/device behavior aligned with `@arkstack/auth` conventions.
67+
4. Update database migrations and models together when auth persistence changes.
68+
5. Add tests for login, logout, protected routes, token/session behavior, and error responses.
69+
70+
## Work on Notifications
71+
72+
1. Inspect notification classes, drivers, and templates.
73+
2. Use the notification module's channel abstractions for mail, SMS, or database notifications.
74+
3. Keep mail templates under the existing view/resource convention.
75+
4. Use config/env values for provider credentials rather than hard-coding secrets.
76+
5. Add tests around notification formatting and driver dispatch boundaries.
77+
78+
## Work on Filesystem Features
79+
80+
1. Inspect filesystem configuration before writing storage code.
81+
2. Use the `@arkstack/filesystem` API instead of direct provider SDK calls when possible.
82+
3. Run `pnpm ark storage:link` only when links are required.
83+
4. Ask before using `pnpm ark storage:link --force`.
84+
5. Test upload, download, URL, and cleanup behavior without assuming a remote provider is available.
85+
86+
## Add a Custom CLI Command
87+
88+
1. Generate the command with `pnpm ark make:command <Name>`.
89+
2. Edit the generated signature, description, and `handle` method.
90+
3. Keep command output concise and script-friendly.
91+
4. Add tests when the command mutates files, invokes app services, or orchestrates database work.
92+
5. Verify with `pnpm ark --help` or `pnpm ark <signature> --help`.
93+
94+
## Update Documentation
95+
96+
1. Edit VitePress pages under `docs`.
97+
2. Add new guide pages to `docs/.vitepress/config.ts` when they should appear in navigation.
98+
3. Use concise examples that match the current CLI and folder structure.
99+
4. Run `pnpm docs:build` after sidebar, frontmatter, or markdown changes.
100+
101+
## Upgrade or Refactor a Package
102+
103+
1. Inspect package exports in the relevant `packages/*/package.json`.
104+
2. Inspect local tests for the package.
105+
3. Keep public exports backward-compatible unless a breaking change is requested.
106+
4. Update package README files when public behavior changes.
107+
5. Run package tests, then root tests or builds when shared contracts are touched.
108+
109+
## Debug a Failing App
110+
111+
1. Reproduce with the failing script or the smallest relevant test.
112+
2. Check recent changes, route registration, environment variables, and generated build output paths.
113+
3. Use `pnpm ark route:list` for HTTP routing issues.
114+
4. Use migration history and model sync commands for database shape issues.
115+
5. Fix the smallest layer that owns the behavior.
116+
6. Re-run the failing command and one adjacent verification.
117+
118+
## Keep Projects Agent-Friendly
119+
120+
- Keep `package.json` scripts accurate and runnable.
121+
- Keep generated Arkstack primitives in their conventional directories.
122+
- Add tests near the behavior they verify.
123+
- Document custom commands, non-standard stubs, and unusual environment requirements.
124+
- Keep `.env.example` current when adding config.
125+
- Avoid mixing runtime-specific logic into services or models.
126+
- Prefer small, named services over large controller methods when behavior grows.

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,10 @@ npm run dev
6363

6464
To learn how to use Arkstack, see the [Guide](https://arkstack.toneflix.net/guide/getting-started).
6565

66+
## AI Agent Support
67+
68+
Arkstack ships with `SKILLS.md` and `AGENTS.md` for project-aware AI assistance. Feed these files to Claude, Codex, Cursor, or similar agents so they understand Arkstack CLI commands, file conventions, and common workflows before editing scaffolded projects.
69+
6670
---
6771

6872
## Application Structure

‎SKILLS.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Arkstack Agent Skills
2+
3+
This file describes discrete capabilities an AI agent can call when working inside an Arkstack project. It is intended to be provided as project context to tools such as Claude, Codex, Cursor, and other coding agents.
4+
5+
Agents should prefer the project's package manager scripts and the `ark` CLI over hand-written file scaffolding when a first-party command exists.
6+
7+
## Environment Discovery
8+
9+
- Identify the package manager from lockfiles: prefer `pnpm` when `pnpm-lock.yaml` is present.
10+
- Inspect `package.json` scripts before running commands.
11+
- Detect the runtime driver from dependencies: `@arkstack/driver-h3` for H3, `@arkstack/driver-express` for Express.
12+
- Detect full vs lean templates by checking for database files, Arkormx dependencies, and `src/app` structure.
13+
- Read `.env`, `.env.example`, `arkormx.config.ts`, `tsdown.config.ts`, and route files only as needed for the task.
14+
15+
## Project Commands
16+
17+
Use these commands from the Arkstack project root when available:
18+
19+
- `pnpm dev` or `pnpm ark dev`: run the development server through `tsdown` in development mode.
20+
- `pnpm build` or `pnpm ark build`: build the application for production.
21+
- `pnpm test`: run the Vitest test suite.
22+
- `pnpm test:watch`: run Vitest in watch mode.
23+
- `pnpm lint`: run ESLint checks.
24+
- `pnpm lint:fix`: apply ESLint fixes.
25+
- `pnpm ark --help`: list available console commands.
26+
- `pnpm ark <command> --help`: inspect command options before generating or mutating files.
27+
28+
In this monorepo, additional root commands exist:
29+
30+
- `pnpm build:packages`: build all `@arkstack/*` packages.
31+
- `pnpm test:coverage`: run tests with coverage.
32+
- `pnpm docs:dev`: run VitePress documentation locally.
33+
- `pnpm docs:build`: build the documentation site.
34+
- `pnpm docs:preview`: preview the built documentation.
35+
36+
## Route Inspection
37+
38+
Use `pnpm ark route:list` to list registered routes.
39+
40+
Useful options:
41+
42+
- `--path <value>` or `-p <value>`: filter by route path.
43+
- `--method <value>` or `-m <value>`: filter by HTTP method.
44+
45+
Use this before changing controllers, middleware, or route definitions so the agent can verify the effective route table.
46+
47+
## Controller Generation
48+
49+
Use `pnpm ark make:controller <Name>` to create a controller in `src/app/http/controllers`.
50+
51+
Useful options:
52+
53+
- `--api`: generate an API-style controller.
54+
- `--model <Name>` or `-m <Name>`: attach model context and create the model if needed.
55+
- `--factory` or `-f`: create a linked factory when using `--model`.
56+
- `--seeder` or `-s`: create a linked seeder when using `--model`.
57+
- `--migration` or `-x`: create a linked migration when using `--model`.
58+
- `--force`: overwrite an existing generated controller.
59+
60+
Prefer this command over manually copying controller stubs. Generated controllers use driver-specific stubs from `node_modules/@arkstack/driver-<driver>/stubs` or the local `stubs` directory.
61+
62+
## Resource Generation
63+
64+
Use `pnpm ark make:resource <type> <Name>` to generate response resources through Resora.
65+
66+
Common forms:
67+
68+
- `pnpm ark make:resource resource User`
69+
- `pnpm ark make:resource collection UserCollection`
70+
- `pnpm ark make:resource all User`
71+
72+
Use `pnpm ark make:full-resource <Prefix>` to create a resource, collection, and API controller together.
73+
74+
Useful options for `make:full-resource`:
75+
76+
- `--model <Name>` or `-m <Name>`: attach model context.
77+
- `--factory` or `-f`: create a linked factory.
78+
- `--seeder` or `-s`: create a linked seeder.
79+
- `--migration` or `-x`: create a linked migration.
80+
- `--force`: overwrite generated resource/controller files.
81+
82+
## Database and Modeling
83+
84+
Full Arkstack templates use Arkormx through the Arkstack CLI.
85+
86+
Available database skills:
87+
88+
- `pnpm ark make:model <Name>`: create a model.
89+
- `pnpm ark make:migration <name>`: create a migration.
90+
- `pnpm ark make:factory <Name>`: create a model factory.
91+
- `pnpm ark make:seeder <Name>`: create a seeder.
92+
- `pnpm ark migrate`: run pending migrations.
93+
- `pnpm ark migrate:fresh`: rebuild the database from scratch. Ask for explicit user approval before running because it is destructive.
94+
- `pnpm ark migrate:rollback`: roll back migrations. Ask for approval before running against non-local data.
95+
- `pnpm ark migrate:history`: inspect migration history.
96+
- `pnpm ark models:sync`: sync model files with the database schema.
97+
- `pnpm ark seed`: run seeders.
98+
99+
Conventions:
100+
101+
- Models belong in `src/app/models` in scaffolded apps.
102+
- Migrations belong in `src/database/migrations`.
103+
- Factories belong in `src/database/factories`.
104+
- Seeders belong in `src/database/seeders`.
105+
- Use `arkormx.config.ts` for database build output and schema configuration.
106+
107+
## View Generation
108+
109+
Use `pnpm ark make:view <name>` to create an Edge view in `src/resources/views`.
110+
111+
Conventions:
112+
113+
- Dots and slashes become nested view paths.
114+
- `.edge` is appended automatically.
115+
- Use `--force` only when intentionally replacing an existing view.
116+
117+
## Storage Links
118+
119+
Use `pnpm ark storage:link` when the filesystem package is installed and the app defines `filesystem.links`.
120+
121+
Useful option:
122+
123+
- `--force`: remove existing links before creating new ones. Ask for confirmation before using this on an existing project.
124+
125+
## Custom Console Commands
126+
127+
Use `pnpm ark make:command <Name>` to create a command class in `src/app/console/commands`.
128+
129+
Conventions:
130+
131+
- Generated command class names end with `Command`.
132+
- Generated command signatures default to `app:<lowercase-command-name>`.
133+
- Custom commands are auto-discovered by the console kernel.
134+
135+
## File Editing Skills
136+
137+
Agents can safely edit these common Arkstack areas when the task calls for it:
138+
139+
- `src/routes`: route registration.
140+
- `src/app/http/controllers`: HTTP controllers.
141+
- `src/app/http/middlewares`: middleware.
142+
- `src/app/http/resources`: resource and collection response shaping.
143+
- `src/app/models`: application models.
144+
- `src/app/services`: business logic.
145+
- `src/app/console/commands`: custom commands.
146+
- `src/database/migrations`: database migrations.
147+
- `src/database/factories`: test or seed factories.
148+
- `src/database/seeders`: seed data.
149+
- `src/resources/views`: Edge templates.
150+
- `src/config` or `config`: configuration files.
151+
- `tests`: Vitest tests.
152+
- `docs`: VitePress documentation.
153+
154+
Rules:
155+
156+
- Prefer generated files for new Arkstack primitives, then edit the generated result.
157+
- Keep runtime-specific code inside driver, middleware, or bootstrap boundaries.
158+
- Keep business logic in services or framework-neutral modules when practical.
159+
- Do not edit generated build output such as `dist`, `.arkstack/build`, or coverage artifacts.
160+
161+
## Testing and Verification
162+
163+
Pick the smallest useful verification for the change:
164+
165+
- Run `pnpm test` after behavior changes.
166+
- Run targeted Vitest files when the project supports them.
167+
- Run `pnpm lint` after broad TypeScript or formatting changes.
168+
- Run `pnpm build` after package exports, runtime entrypoints, CLI commands, or build config changes.
169+
- Run `pnpm docs:build` after VitePress docs or sidebar changes.
170+
- Run `pnpm ark route:list` after route/controller/middleware changes.
171+
172+
## Safety Rules
173+
174+
- Ask before running destructive database commands such as `migrate:fresh`, broad rollback commands, or forced storage links.
175+
- Ask before deleting user files or replacing existing generated files with `--force`.
176+
- Do not commit, publish, or release unless explicitly requested.
177+
- Do not assume a database is disposable unless the user says it is local/test data.
178+
- Preserve project conventions and inspect nearby files before introducing a new pattern.

‎docs/.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ export default defineConfig({
6464
{
6565
text: 'More',
6666
items: [
67+
{ text: 'AI Agents', link: '/more/agents' },
6768
{ text: 'Roadmap', link: '/more/roadmap' },
6869
{ text: 'Contributing', link: '/more/contributing' },
6970
{ text: 'Changelog', link: '/more/changelog' },

0 commit comments

Comments
 (0)