Skip to content

Commit 64d9ffe

Browse files
2chanhaeng2chanhaeng
committed
Separate create-integration-package skill
1 parent 2f8ff99 commit 64d9ffe

20 files changed

Lines changed: 324 additions & 175 deletions

File tree

‎.agents/skills/add-to-fedify-init/SKILL.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
name: add-to-fedify-init
3+
description: >-
4+
This skill is used to add an integration package to the @fedify/init
5+
package so that users can select the new framework via the `fedify init`
6+
command, and to test it with `mise test:init`.
7+
argument-hint: "Provide the name of the web framework to register in @fedify/init."
8+
---
9+
10+
<!-- deno-fmt-ignore-file -->
11+
12+
Adding an integration package to `@fedify/init`
13+
===============================================
14+
15+
Follow these steps in order to register the integration package in
16+
`@fedify/init` and verify it works.
17+
18+
1. Add to `@fedify/init`
19+
2. Test with `mise test:init`
20+
3. Lint, format, and final checks
21+
22+
23+
Add to `@fedify/init`
24+
---------------------
25+
26+
Add the new package to the `@fedify/init` package so users can select the
27+
new framework via the `fedify init` command. Follow these steps.
28+
29+
Steps may require code modifications not explicitly listed. For example,
30+
if the new package needs specific configuration, utility functions in
31+
`packages/init/src/webframeworks/utils.ts` may need updating. Make
32+
modifications consistent with the existing code style and context.
33+
34+
### Write the `WebFrameworkDescription` object
35+
36+
Create a `packages/init/src/webframeworks/framework.ts` file and write the
37+
`WebFrameworkDescription` object, referring to <init/framework.ts>. Check
38+
the specifications in the comments in `packages/init/src/types.ts` for
39+
details.
40+
41+
### Add to the `WEB_FRAMEWORK` array
42+
43+
Add the new framework name to the end of the `WEB_FRAMEWORK` array in
44+
`packages/init/src/const.ts`.
45+
46+
~~~~ typescript
47+
export const WEB_FRAMEWORK = [
48+
// ... other frameworks
49+
"framework", // Fill with the framework name
50+
];
51+
~~~~
52+
53+
### Add to the `webFrameworks` object
54+
55+
Add the new `WebFrameworkDescription` object in alphabetical order to the
56+
`webFrameworks` object in `packages/init/src/webframeworks/mod.ts`.
57+
58+
~~~~ typescript
59+
// packages/init/src/webframeworks/mod.ts
60+
61+
// ... other imports
62+
import framework from "./framework.ts"; // Fill with the framework name
63+
64+
const webFrameworks: Record<string, WebFrameworkDescription> = {
65+
// ... other frameworks
66+
framework, // Fill with the framework name
67+
};
68+
~~~~
69+
70+
### Add templates in `packages/init/src/templates/framework/`
71+
72+
If additional files need to be generated, add template files under the
73+
`packages/init/src/templates/framework/` directory. Template files must
74+
end with the `.tpl` extension appended to their base name. Then, in
75+
`packages/init/src/webframeworks/framework.ts`, load the templates using
76+
the `readTemplate` function defined in `packages/init/src/lib.ts` and add
77+
them to the `WebFrameworkDescription.init().files` object.
78+
79+
80+
Test with `mise test:init`
81+
--------------------------
82+
83+
Run `mise test:init` to verify that the new package is generated and runs
84+
correctly. If a test fails, the output and error file paths are printed;
85+
read them to diagnose the issue.
86+
87+
Running `mise test:init` without arguments tests all option combinations
88+
and can take a very long time. Use appropriate options to narrow the test
89+
scope.
90+
91+
Immediately remove test paths after completing the tests and analyzing any
92+
resulting errors.
93+
94+
At a minimum, test the following three combinations.
95+
96+
- `mise test:init -w framework -m in-process -k in-memory --no-dry-run`:
97+
Tests the new framework with the in-memory KV store and in-process message
98+
queue, which are the most basic options. This combination verify that the
99+
newly created package can be used without issues by minimizing dependencies
100+
on other environments.
101+
- `mise test:init -w framework`: Tests all package manager, KV store,
102+
and message queue combinations with the framework selected. If a
103+
required database is not installed or running, this combinations are
104+
useless. Therefore, if the test output indicates that the databases are
105+
not running, don't use this combination ever again for the session.
106+
Instead, use the previous one or the next one.
107+
- `mise test:init -m in-process -k in-memory --no-dry-run`: Fixes the
108+
KV store and message queue and tests all web framework and package
109+
manager combinations. This test is mandatory if you modified logic
110+
beyond just writing the `WebFrameworkDescription` object.
111+
112+
For details on options, run `mise test:init --help`.
113+
114+
Some frameworks or combinations may be untestable. Analyze the test
115+
results; if there are impossible combinations, identify the reason and add
116+
the combination and reason as a key-value pair to the
117+
`BANNED_LOOKUP_REASONS` object in
118+
`packages/init/src/test/lookup.ts`.
119+
120+
121+
Lint, format, and final checks
122+
------------------------------
123+
124+
Add keywords related to the framework in `.hongdown.toml` and `cspell.json` in
125+
root path.
126+
127+
After implementation, run `mise run fmt && mise check`.
128+
If there are lint or format errors, fix them and run the command again until
129+
there are no errors.

.agents/skills/create-integration-package/init/framework.ts renamed to .agents/skills/add-to-fedify-init/init/framework.ts

File renamed without changes.

.agents/skills/create-integration-package/example/ARCHITECTURE.md renamed to .agents/skills/create-example-app-with-integration/ARCHITECTURE.md

File renamed without changes.

.agents/skills/create-integration-package/example/DESIGN.md renamed to .agents/skills/create-example-app-with-integration/DESIGN.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -247,10 +247,10 @@ Static assets
247247

248248
All visual assets live in *public/* and are served at the site root:
249249

250-
- *style.css* —- Complete stylesheet
251-
- *theme.js* —- Dark/light class toggle script
252-
- *demo-profile.png* —- Demo actor avatar
253-
- *fedify-logo.svg* —- Fedify logo for badge and branding
250+
- *style.css* — Complete stylesheet
251+
- *theme.js* — Dark/light class toggle script
252+
- *demo-profile.png* — Demo actor avatar
253+
- *fedify-logo.svg* — Fedify logo for badge and branding
254254

255255
### Following / followers list
256256

@@ -272,14 +272,14 @@ full routing specification.
272272

273273
Top to bottom:
274274

275-
1. **Search** —- text input with debounced lookup; result card appears
275+
1. **Search** — text input with debounced lookup; result card appears
276276
inline below
277-
2. **User info** —- profile header (gradient, avatar, name, handle,
277+
2. **User info** — profile header (gradient, avatar, name, handle,
278278
bio)
279-
3. **Following** —- count + account list with unfollow buttons
280-
4. **Followers** —- count + account list
281-
5. **Compose** —- textarea + submit button
282-
6. **Posts** —- reverse-chronological post cards, each linking to the
279+
3. **Following** — count + account list with unfollow buttons
280+
4. **Followers** — count + account list
281+
5. **Compose** — textarea + submit button
282+
6. **Posts** — reverse-chronological post cards, each linking to the
283283
detail page
284284

285285
### Actor profile (`/users/{identifier}`)

‎.agents/skills/create-example-app-with-integration/SKILL.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
name: create-example-app-with-integration
3+
description: >-
4+
This skill is used to create an example application for a web framework
5+
integration package and to test it with `mise test:examples`.
6+
argument-hint: "Provide the name of the web framework to create an example for."
7+
---
8+
9+
<!-- deno-fmt-ignore-file -->
10+
11+
Creating an example for an integration package
12+
==============================================
13+
14+
Follow these steps in order to create the example application and verify
15+
it works.
16+
17+
1. Set up the example project
18+
2. Implement the example app
19+
3. Test the example with `mise test:examples`
20+
4. Lint, format, and final checks
21+
22+
23+
Reference documents
24+
-------------------
25+
26+
Two reference documents describe what the example must do and how it must
27+
look. Both are references only — do not create these files in the actual
28+
generated example app.
29+
30+
### <ARCHITECTURE.md>
31+
32+
Defines the example's functional behavior. Consult it for:
33+
34+
- **Middleware integration**: How to register the Fedify middleware so it
35+
intercepts ActivityPub requests before application routes.
36+
- **Reverse proxy support**: When and how to apply
37+
`getXForwardedRequest` from `x-forwarded-fetch`.
38+
- **Routing**: The complete list of routes (`GET /`, `GET /users/…`,
39+
`POST /post`, `POST /follow`, `POST /unfollow`, `GET /events`, etc.)
40+
with their expected request/response behavior.
41+
- **Server-sent events**: How the `/events` endpoint keeps an open SSE
42+
connection and broadcasts changes to the client.
43+
- **Server-side data access**: How to use Fedify's `RequestContext` to
44+
bridge between the framework routing layer and the federation layer.
45+
- **Federation** and **Storing**: Which source files to set up
46+
(`src/federation.ts`, `src/store.ts`) and the template files they are
47+
based on (<example/src/federation.ts>, <example/src/store.ts>).
48+
- **Logging**: How to use `@logtape/logtape` and `src/logging.ts`.
49+
50+
### <DESIGN.md>
51+
52+
Defines the example's visual presentation. Consult it for:
53+
54+
- **Visual theme & atmosphere**: Light/dark theme with
55+
`prefers-color-scheme` detection.
56+
- **Color palette & roles**: Surface, accent, neutral, and shadow tokens.
57+
- **Typography rules**: Font family, size hierarchy, and weight
58+
principles.
59+
- **Component stylings**: Profile header, avatar, cards, search input,
60+
compose form, buttons, back link, and Fedify badge.
61+
- **Layout principles**: Spacing, containers, grid, and whitespace.
62+
- **Responsive behavior**: Single breakpoint at `768px` and mobile
63+
adaptations.
64+
- **Static assets**: Files to serve from `public/` (<example/public/\*>).
65+
- **Page structure**: Detailed layout of the home page, actor profile
66+
page, and post detail page.
67+
68+
69+
Set up the example project
70+
--------------------------
71+
72+
Create an `examples/framework/` app and write an example for the new
73+
package. Unless the framework itself prevents it, support both Deno and
74+
Node.js environments. If Deno is supported, add a *deno.json* based on
75+
<example/deno.json>; if Node.js is supported, add *package.json* based on
76+
<example/package.jsonc> and *tsdown.config.ts*. Depending on the supported
77+
environments, add the example path to the `workspace` field in
78+
the root *deno.json* and to the `packages` field in
79+
*pnpm-workspace.yaml*.
80+
81+
If the framework is backend-only and needs a frontend framework, and there
82+
is no natural pairing like solidstart-solid, use Hono.
83+
84+
Copy the template files from <example/\*> as-is and modify as needed.
85+
86+
If the framework does not have a prescribed entry point, use `src/main.ts`
87+
as the application entry point. Define and export the framework app in
88+
`src/app.ts`, then import and run it from the entry file. Import
89+
`src/logging.ts` in the entry file to initialize `@logtape/logtape`.
90+
When logging is needed, use the `getLogger` function from `@logtape/logtape`
91+
to create a logger.
92+
93+
94+
Implement the example app
95+
-------------------------
96+
97+
Follow the specifications in <ARCHITECTURE.md> and <DESIGN.md> to
98+
implement the example. In particular:
99+
100+
- Register the Fedify middleware in `src/app.ts` per the “Middleware
101+
integration” and “Reverse proxy support” sections of
102+
<ARCHITECTURE.md>.
103+
- Set up federation logic in `src/federation.ts` based on
104+
<example/src/federation.ts>. Set up in-memory stores in `src/store.ts`
105+
based on <example/src/store.ts>.
106+
- Implement all routes listed in the “Routing” section of
107+
<ARCHITECTURE.md>, using `RequestContext` as described in the
108+
“Server-side data access” section.
109+
- Render HTML pages according to <DESIGN.md>. Serve static assets from
110+
the `public/` directory (copy from <example/public/\*>).
111+
- Implement the SSE endpoint per the “Server-sent events” section of
112+
<ARCHITECTURE.md>.
113+
114+
115+
Test the example with `mise test:examples`
116+
------------------------------------------
117+
118+
Register the new example in `examples/test-examples/mod.ts`. Read the
119+
comments above the example registry arrays in that file to determine
120+
which array is appropriate and what fields are required. Follow the
121+
patterns of existing entries.
122+
123+
Before running the tests, ensure that the tunneling service is usable.
124+
The tests use the tunneling service `pinggy.io` to make the example app
125+
accessible to the test suite. If the tunneling service is not usable,
126+
the tests may never finish or may fail due to a connection error.
127+
128+
While developing the example, run only the new example to iterate
129+
quickly:
130+
131+
~~~~ bash
132+
mise test:examples framework
133+
~~~~
134+
135+
where `framework` is the `name` field of the registered entry. Pass
136+
`--debug` for verbose output if the test fails.
137+
138+
After the example is complete, run the full suite once to confirm nothing
139+
is broken:
140+
141+
~~~~ bash
142+
mise test:examples
143+
~~~~
144+
145+
146+
Lint, format, and final checks
147+
------------------------------
148+
149+
Add keywords related to the framework in `.hongdown.toml` and `cspell.json` in
150+
root path.
151+
152+
After implementation, run `mise run fmt && mise check`.
153+
If there are lint or format errors, fix them and run the command again until
154+
there are no errors.

.agents/skills/create-integration-package/example/README.md renamed to .agents/skills/create-example-app-with-integration/example/README.md

File renamed without changes.

.agents/skills/create-integration-package/example/deno.jsonc renamed to .agents/skills/create-example-app-with-integration/example/deno.jsonc

File renamed without changes.

.agents/skills/create-integration-package/example/package.jsonc renamed to .agents/skills/create-example-app-with-integration/example/package.jsonc

File renamed without changes.

.agents/skills/create-integration-package/example/public/demo-profile.png renamed to .agents/skills/create-example-app-with-integration/example/public/demo-profile.png

File renamed without changes.

.agents/skills/create-integration-package/example/public/fedify-logo.svg renamed to .agents/skills/create-example-app-with-integration/example/public/fedify-logo.svg

File renamed without changes.

0 commit comments

Comments
 (0)