@fedify/cli 2.5.0-dev.2496 → 2.5.0-dev.2504

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/dist/deno.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import "temporal-polyfill";
2
2
  //#region deno.json
3
- var version = "2.5.0-dev.2496+e18c05f8";
3
+ var version = "2.5.0-dev.2504+fdeb138d";
4
4
  //#endregion
5
5
  export { version };
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "@fedify/cli",
3
- "version": "2.5.0-dev.2496+e18c05f8",
3
+ "version": "2.5.0-dev.2504+fdeb138d",
4
4
  "type": "module",
5
5
  "files": [
6
6
  "README.md",
7
- "dist/"
7
+ "dist/",
8
+ "skills/"
8
9
  ],
9
10
  "bin": {
10
11
  "fedify": "./dist/mod.js"
@@ -88,14 +89,14 @@
88
89
  "temporal-polyfill": "^1.0.1",
89
90
  "valibot": "^1.4.0",
90
91
  "yaml": "^2.9.0",
91
- "@fedify/init": "2.5.0-dev.2496+e18c05f8",
92
- "@fedify/fedify": "2.5.0-dev.2496+e18c05f8",
93
- "@fedify/relay": "2.5.0-dev.2496+e18c05f8",
94
- "@fedify/sqlite": "2.5.0-dev.2496+e18c05f8",
95
- "@fedify/vocab-runtime": "2.5.0-dev.2496+e18c05f8",
96
- "@fedify/vocab-tools": "2.5.0-dev.2496+e18c05f8",
97
- "@fedify/webfinger": "2.5.0-dev.2496+e18c05f8",
98
- "@fedify/vocab": "2.5.0-dev.2496+e18c05f8"
92
+ "@fedify/init": "2.5.0-dev.2504+fdeb138d",
93
+ "@fedify/fedify": "2.5.0-dev.2504+fdeb138d",
94
+ "@fedify/sqlite": "2.5.0-dev.2504+fdeb138d",
95
+ "@fedify/vocab": "2.5.0-dev.2504+fdeb138d",
96
+ "@fedify/relay": "2.5.0-dev.2504+fdeb138d",
97
+ "@fedify/vocab-runtime": "2.5.0-dev.2504+fdeb138d",
98
+ "@fedify/webfinger": "2.5.0-dev.2504+fdeb138d",
99
+ "@fedify/vocab-tools": "2.5.0-dev.2504+fdeb138d"
99
100
  },
100
101
  "devDependencies": {
101
102
  "@types/bun": "^1.2.23",
@@ -105,12 +106,20 @@
105
106
  "typescript": "^6.0.0",
106
107
  "@fedify/fixture": "2.0.0"
107
108
  },
109
+ "agents": {
110
+ "skills": [
111
+ {
112
+ "name": "fedify-cli",
113
+ "path": "./skills/fedify-cli"
114
+ }
115
+ ]
116
+ },
108
117
  "scripts": {
109
118
  "build:self": "tsdown",
110
119
  "build": "pnpm --filter @fedify/cli... run build:self",
111
120
  "prepublish": "pnpm build",
112
121
  "pretest": "pnpm build",
113
- "test": "node --test --experimental-transform-types 'src/**/*.test.ts' '!src/init/test/**'",
122
+ "test": "node --test --experimental-transform-types 'src/**/*.test.ts' '!src/init/test/**' scripts/pack-skills.test.mjs",
114
123
  "test-init": "deno task test-init",
115
124
  "pretest:bun": "pnpm build",
116
125
  "test:bun": "bun test --timeout 60000",
@@ -0,0 +1,274 @@
1
+ ---
2
+ name: fedify-cli
3
+ description: >-
4
+ Use the fedify CLI to inspect and debug ActivityPub servers, including
5
+ servers built without the Fedify framework. Apply when looking up actors
6
+ or objects, diagnosing handle discovery or federation failures, fetching
7
+ WebFinger or NodeInfo, traversing collections or reply chains, resolving
8
+ portable objects through gateways, testing delivery with an
9
+ ephemeral inbox, exposing a local server through a tunnel, running a test
10
+ relay, or scaffolding a project with fedify init. Covers installation,
11
+ version checks, command selection, output interpretation, and remote
12
+ effects. Use for fedify CLI tasks even outside a JavaScript project.
13
+ ---
14
+
15
+ Fedify CLI skill
16
+ ================
17
+
18
+ Use `fedify` to inspect ActivityPub servers without writing an application.
19
+ The target server can use any framework. For building an application with
20
+ Fedify's TypeScript APIs, use the separate `fedify` skill.
21
+
22
+ Read <https://fedify.dev/cli.md> for detailed options. The documentation is
23
+ available as raw Markdown with the `.md` suffix; remove that suffix when
24
+ presenting links to the user. These examples target Fedify CLI 2.5.0.
25
+ If the installed version differs, its `--help` output takes precedence over
26
+ these examples.
27
+
28
+
29
+ Check the command first
30
+ -----------------------
31
+
32
+ ~~~~ sh
33
+ fedify --version
34
+ fedify --help
35
+ fedify lookup --help
36
+ ~~~~
37
+
38
+ Check the chosen subcommand's `--help` before using version-dependent flags.
39
+ Use a project-local executable when the project already provides one. In a
40
+ Fedify source checkout, follow its contributor instructions and use
41
+ `mise run cli -- <arguments>`.
42
+
43
+ If the command is missing, choose an installation method that fits the user's
44
+ runtime. For example, with Node.js:
45
+
46
+ ~~~~ sh
47
+ npm install -g @fedify/cli
48
+ ~~~~
49
+
50
+ Deno, Bun, Homebrew, Scoop, mise, and standalone executables are covered at
51
+ <https://fedify.dev/cli.md#installation>. Installing the CLI executable and
52
+ installing this skill are separate steps; see
53
+ <https://fedify.dev/install.md#agentic-skill>.
54
+
55
+ Configuration files can supply defaults, including options that contact
56
+ remote servers. Inspect relevant defaults before running diagnostics. For
57
+ an isolated invocation, put `--ignore-config` before the subcommand:
58
+
59
+ ~~~~ sh
60
+ fedify --ignore-config lookup @alice@example.com
61
+ ~~~~
62
+
63
+ The domains and handles below are placeholders. Substitute the user's target.
64
+ Discovery and lookup commands contact remote servers and may appear in their
65
+ logs. Traversal fetches additional pages and objects. Keep the request volume
66
+ appropriate to the diagnostic task.
67
+
68
+
69
+ Choose a diagnostic command
70
+ ---------------------------
71
+
72
+ | Question | Command | What to inspect |
73
+ | ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------ |
74
+ | Where does a handle point? | `fedify webfinger @alice@example.com` | The JSON resource descriptor's `subject`, `aliases`, and ActivityPub `self` link. |
75
+ | Can the actor or object be fetched? | `fedify lookup @alice@example.com` | The parsed vocabulary object, its `id`, type, inbox, and advertised collection URLs. |
76
+ | What software does the instance advertise? | `fedify nodeinfo example.com` | Software name/version, protocols, usage, and registration policy. |
77
+
78
+ WebFinger discovers a resource; it does not fetch the actor document.
79
+ `lookup` resolves and dereferences the resource. NodeInfo describes an
80
+ instance and does not establish that a particular actor or inbox works.
81
+
82
+ ### Investigate a lookup failure
83
+
84
+ 1. Run `webfinger` for a handle and inspect the `self` link whose type is
85
+ `application/activity+json` or `application/ld+json` with the
86
+ ActivityStreams profile. A profile-page link is for browsers and may not be
87
+ the actor's ID.
88
+
89
+ 2. Run `lookup` on that `self` URL. If this works while the handle fails,
90
+ focus on WebFinger discovery, redirects, and the advertised link.
91
+
92
+ 3. Choose a JSON output format after a successful lookup:
93
+
94
+ ~~~~ sh
95
+ fedify lookup --raw https://example.com/users/alice
96
+ fedify nodeinfo --raw example.com
97
+ ~~~~
98
+
99
+ `lookup` normally prints a vocabulary object. Its `--raw` option
100
+ serializes the parsed object back to JSON-LD. `--compact` and `--expand`
101
+ select other JSON-LD forms. These three format options are mutually
102
+ exclusive, and all require successful parsing. To investigate a parsing
103
+ failure, request the resource directly with an ActivityPub `Accept`
104
+ header:
105
+
106
+ ~~~~ sh
107
+ curl -i -H 'Accept: application/activity+json' https://example.com/users/alice
108
+ ~~~~
109
+
110
+ Inspect the status, `Content-Type`, and response body. This unsigned
111
+ request may receive a different response from a server that requires
112
+ signed fetch.
113
+
114
+ 4. Record the exact command, CLI version, exit status, and error. Check
115
+ DNS/TLS, HTTP errors, redirects, and content negotiation as indicated by
116
+ the evidence. Do not conclude from a single failed request that an account
117
+ does not exist. Use `fedify --debug lookup <target>` when more detail is
118
+ needed; redact private content and credentials before sharing logs.
119
+
120
+ For a server requiring signed requests, consider:
121
+
122
+ ~~~~ sh
123
+ fedify lookup --authorized-fetch @alice@example.com
124
+ ~~~~
125
+
126
+ This creates a one-time key pair and a temporary public server through a
127
+ tunnel so the remote server can fetch the signing key. It does not log in as
128
+ the user's account or grant access to private posts. Explain the exposure
129
+ before running it and use it only within the user's authorized task.
130
+
131
+ Do not enable `--allow-private-address` for arbitrary remote data. It permits
132
+ fetching private or loopback addresses; reserve it for an explicitly intended
133
+ local test. See <https://fedify.dev/cli.md> for signature options, timeouts,
134
+ and other version-specific diagnostics.
135
+
136
+ ### Traverse a collection
137
+
138
+ Copy the collection URL from the fetched actor, then inspect it before
139
+ traversing it:
140
+
141
+ ~~~~ sh
142
+ fedify lookup https://example.com/users/alice/outbox
143
+ fedify lookup --traverse https://example.com/users/alice/outbox
144
+ ~~~~
145
+
146
+ Without `--traverse`, the result is the collection itself. With it, the
147
+ command follows collection pages and prints their items. Each target must
148
+ resolve to a collection, so passing the actor URL is insufficient. Separate
149
+ results use `----` by default; do not treat the entire stream as one JSON
150
+ array. Traversal can fetch many pages and objects. Keep errors visible while
151
+ diagnosing; `--suppress-errors` can produce partial results and does not prove
152
+ every item was retrieved. Use the CLI reference for separators, output files,
153
+ and relationship recursion rather than guessing flags.
154
+
155
+
156
+ Advanced diagnostic recipes
157
+ ---------------------------
158
+
159
+ ### Reconstruct a conversation from one post
160
+
161
+ Follow a post's reply targets to inspect its ancestors without relying on a
162
+ server's web UI:
163
+
164
+ ~~~~ sh
165
+ fedify lookup --recurse replyTarget --recurse-depth 5 --reverse https://example.com/posts/leaf
166
+ fedify lookup --recurse quote --recurse-depth 3 https://example.com/posts/quoted
167
+ ~~~~
168
+
169
+ `replyTarget` is the vocabulary property name for ActivityStreams
170
+ `inReplyTo`. `quote` and `quoteUrl` follow quote relationships instead. A
171
+ depth limit bounds the walk; it does not establish that the conversation is
172
+ complete. `--reverse` buffers results before printing them in reverse order,
173
+ which can make an ancestor chain easier to read. Relationship recursion and
174
+ `--traverse` are mutually exclusive: use recursion for links between objects
175
+ and traversal for collection membership. This can help locate a broken link
176
+ or a serialization difference between servers.
177
+
178
+ ### Compare discovery before and after an account move
179
+
180
+ Use multiple targets to inspect both handles in one terminal session:
181
+
182
+ ~~~~ sh
183
+ fedify webfinger @alice@old.example @alice@new.example
184
+ fedify lookup --raw @alice@old.example @alice@new.example
185
+ ~~~~
186
+
187
+ Compare WebFinger `self` links, actor IDs, and any advertised `movedTo` or
188
+ `alsoKnownAs` relationships. A matching display name is not evidence that two
189
+ actors are the same identity. This is an inspection workflow; it does not
190
+ move accounts or send a `Move` activity. For a reproducible diagnostic
191
+ artifact, `lookup --raw --output actor.json <actor-url>` saves the parsed
192
+ actor as JSON-LD. Review private content before sharing it, and remember that a
193
+ multi-target output uses separators rather than forming a JSON array.
194
+
195
+ ### Separate portable identity from gateway availability
196
+
197
+ On versions supporting FEP-ef61 portable objects, provide a gateway for a
198
+ bare portable ID:
199
+
200
+ ~~~~ sh
201
+ fedify lookup --gateway https://gateway.example 'ap://did:key:z6Mk.../actor'
202
+ ~~~~
203
+
204
+ Replace the abbreviated DID and path with the complete ID under test.
205
+ Portable IDs carry identity independently of the serving host. A gateway URL
206
+ or an ID with `@gateway` location hints can supply the fetch location instead
207
+ of `--gateway`. Distinguish a gateway fetch failure from an integrity-proof
208
+ failure: successfully receiving JSON does not mean its proof is valid.
209
+ The CLI validates the portable object's integrity proof before accepting it.
210
+ See <https://fedify.dev/cli.md#looking-up-portable-objects> for identifier
211
+ forms and gateway rules.
212
+
213
+
214
+ Create a project
215
+ ----------------
216
+
217
+ ~~~~ sh
218
+ fedify init my-federated-app
219
+ ~~~~
220
+
221
+ `init` runs an interactive wizard for runtime, package manager, framework,
222
+ KV store, and message queue. Choose an intended new directory and resolve
223
+ those choices with the user before running the wizard. Scaffolding writes
224
+ files and may install dependencies. It is useful for a new Fedify app, but is
225
+ not needed for CLI-only diagnosis. See
226
+ <https://fedify.dev/cli.md#fedify-init-initializing-a-fedify-project>.
227
+
228
+
229
+ Receive test activities
230
+ -----------------------
231
+
232
+ ~~~~ sh
233
+ fedify inbox
234
+ ~~~~
235
+
236
+ This starts a temporary actor and inbox with a public HTTPS tunnel. Use the
237
+ printed actor handle or URI as a recipient from the server under test, then
238
+ inspect the logged activity type, HTTP status, and request-details URL. A
239
+ successful HTTP response alone does not establish that an application's
240
+ business logic handled an activity. Stop the process with Ctrl-C when done;
241
+ the actor and tunnel are short-lived.
242
+
243
+ For a local-only test, check `fedify inbox --help` for `--no-tunnel`. Remote
244
+ peers cannot reach a loopback-only endpoint.
245
+
246
+ `--follow` sends Follow activities to the named actors, and `--accept-follow`
247
+ can send Accept activities. These affect remote servers; use them only when
248
+ the user has authorized that interaction. Inspect configuration defaults so
249
+ a plain `inbox` invocation does not unexpectedly follow or accept actors.
250
+ See <https://fedify.dev/cli.md#fedify-inbox-ephemeral-inbox-server>.
251
+
252
+
253
+ Expose a local server or test a relay
254
+ -------------------------------------
255
+
256
+ ~~~~ sh
257
+ fedify tunnel 3000
258
+ fedify relay --protocol mastodon
259
+ ~~~~
260
+
261
+ `tunnel` exposes an existing local HTTP service to the public internet. Use
262
+ it only for the intended development service, with test data. Ensure that
263
+ the service recognizes its public origin, including forwarded headers where
264
+ appropriate, so actor IDs do not point to localhost.
265
+
266
+ `relay` runs an ActivityPub relay and forwards activities between participating
267
+ servers. It opens a public tunnel by default and uses in-memory storage
268
+ unless persistence is configured. Choose Mastodon or LitePub according to
269
+ the test, and use controlled participants; accepting subscriptions and
270
+ forwarding activities have remote effects. Starting a relay is not a passive
271
+ connectivity check. Stop temporary servers when the test ends.
272
+
273
+ Read <https://fedify.dev/cli.md> for tunnel providers, relay persistence,
274
+ subscription controls, and local-only modes.