Skip to content

plugin-integration - manifest for skills #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
godronus merged 2 commits into from
Apr 7, 2026
Merged

plugin-integration - manifest for skills #116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
89f2a29
wip - plugin-integration
godronus Apr 7, 2026
38d31ad
plugin manifest updated
godronus Apr 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,6 @@ yarn-error.log

# Using pnpm
package-lock.json

# FastEdge debugger artifacts
**/.fastedge-debug/
37 changes: 37 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
doc_type: policy
audience: bot
lang: en
tags: ['ai-agents', 'rules', 'critical', 'codex']
last_modified: 2026-04-02T00:00:00Z
copyright: '© 2026 gcore.com'
---

# RULES FOR AI AGENTS

TL;DR: Keep command output short. Do not take actions unless asked. Do not waste tokens on
experiments. Do only what is asked.

# COMMUNICATION STYLE

- Use English by default; if the user writes in another language, use that language
- Use an informal tone, avoid formal business language
- Question ideas and suggest alternatives — do not just agree with everything
- Think for yourself instead of agreeing to be polite

# INVARIANTS

- NEVER do anything beyond the assigned task
- NEVER change code that was not asked to change
- NEVER "improve" or "optimize" without a clear request
- NEVER use scripts for mass code replacements
- NEVER make architecture decisions on your own
- ALWAYS keep command output short — every extra line = wasted tokens
- ALWAYS think before acting — do not repeat checks, remember context
- ALWAYS ask an expert when the solution is not clear
- ALWAYS tell apart an observation from an action request: observation ("works oddly") → discuss, DO
NOT fix request ("fix this") → act

# PROJECT CONTEXT

see CLAUDE.md
6 changes: 6 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# AI Agent Instructions for FastEdge JS SDK

## Governance (REQUIRED)

Read `AGENTS.md` for company-wide agent rules. These are mandatory and override any conflicting behavior. Key rules: never go beyond the assigned task, never change code that was not asked to change, never "improve" or "optimize" without a clear request, always distinguish observations from action requests.

---

## CRITICAL: Read Smart, Not Everything

**DO NOT read all context files upfront.** This repository uses a **discovery-based context system** to minimize token usage while maximizing effectiveness.
Expand Down
11 changes: 11 additions & 0 deletions context/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,17 @@ When this file grows large, use grep to search — don't read linearly.

---

## [2026-03-31] — Examples and Terminology Conventions

### Overview
Documented conventions for example maintenance and user-facing terminology.

### Decisions
- Every example must have its own `README.md` and an entry in the top-level `examples/README.md` index
- In all user-facing documentation (READMEs, docs), always use "environment variables" — never "dictionary variables". The `dictionary` package is an internal implementation detail for accessing environment variables on the platform, not a user-facing concept

---

## [2026-03-26] — Examples Consolidation

### Overview
Expand Down
5 changes: 4 additions & 1 deletion context/CONTEXT_INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,13 @@
2. Check `github-pages/src/content/docs/reference/` for user-facing docs
3. Run `pnpm run build:types` to verify

### Adding a New Example
### Adding or Editing an Example
1. Browse `examples/` for an existing example similar to your target
2. Each example is standalone with its own `package.json`
3. Install SDK via `npm install --save-dev @gcoredev/fastedge-sdk-js`
4. **Every example MUST have its own `README.md`** explaining what it does
5. **Every example MUST have an entry in `examples/README.md`** (the top-level index)
6. **Terminology**: In READMEs, always refer to "environment variables" — never "dictionary variables". `dictionary` is the internal package name for accessing environment variables, not a user-facing concept

### Changing the Build System
1. Read `development/BUILD_SYSTEM.md`
Expand Down
14 changes: 7 additions & 7 deletions docs/ASSETS_CLI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,13 @@ npx fastedge-assets --version

## Flags

| Flag | Alias | Type | Description |
| ----------------- | ----- | --------- | ----------------------------------------------------------------------------- |
| `--input <path>` | `-i` | `string` | Path to the directory of source assets (e.g. `./public`) |
| `--output <file>` | `-o` | `string` | Output file path for the generated manifest (e.g. `./src/asset-manifest.ts`) |
| `--config <file>` | `-c` | `string` | Path to an asset config file containing `AssetCacheConfig` fields |
| `--version` | `-v` | `boolean` | Print the package version |
| `--help` | `-h` | `boolean` | Print usage information |
| Flag | Alias | Type | Description |
| ----------------- | ----- | --------- | ---------------------------------------------------------------------------- |
| `--input <path>` | `-i` | `string` | Path to the directory of source assets (e.g. `./public`) |
| `--output <file>` | `-o` | `string` | Output file path for the generated manifest (e.g. `./src/asset-manifest.ts`) |
| `--config <file>` | `-c` | `string` | Path to an asset config file containing `AssetCacheConfig` fields |
| `--version` | `-v` | `boolean` | Print the package version |
| `--help` | `-h` | `boolean` | Print usage information |

**Notes:**

Expand Down
43 changes: 25 additions & 18 deletions docs/BUILD_CLI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,14 @@ npx fastedge-build --version

## Options

| Flag | Alias | Type | Description |
| ------------ | ----- | ---------- | -------------------------------- |
| `--input` | `-i` | `String` | Input JavaScript/TypeScript file |
| `--output` | `-o` | `String` | Output WebAssembly file path |
| `--tsconfig` | `-t` | `String` | Path to tsconfig.json |
| `--config` | `-c` | `String[]` | Path(s) to build config files |
| `--help` | `-h` | `Boolean` | Show help |
| `--version` | `-v` | `Boolean` | Show version |
| Flag | Alias | Type | Description |
| -------------- | ----- | ---------- | -------------------------------- |
| `--input` | `-i` | `String` | Input JavaScript/TypeScript file |
| `--output` | `-o` | `String` | Output WebAssembly file path |
| `--tsconfig` | `-t` | `String` | Path to tsconfig.json |
| `--config` | `-c` | `String[]` | Path(s) to build config files |
| `--help` | `-h` | `Boolean` | Show help |
| `--version` | `-v` | `Boolean` | Show version |

## Build Modes

Expand Down Expand Up @@ -127,14 +127,14 @@ export { config };

When `type` is `'static'`, the following fields from `AssetCacheConfig` apply:

| Field | Type | Required | Description |
| ------------------- | ------------------------------ | -------- | -------------------------------------------- |
| `publicDir` | `string` | Yes | Directory containing static files to embed |
| `assetManifestPath` | `string` | Yes | Output path for the generated asset manifest |
| `contentTypes` | `Array<ContentTypeDefinition>` | No | Custom content type mappings |
| `ignoreDotFiles` | `boolean` | No | Skip files beginning with `.` |
| `ignorePaths` | `string[]` | No | Paths to exclude from the manifest |
| `ignoreWellKnown` | `boolean` | No | Skip the `.well-known/` directory |
| Field | Type | Required | Description |
| --------------------- | ------------------------------ | -------- | -------------------------------------------- |
| `publicDir` | `string` | Yes | Directory containing static files to embed |
| `assetManifestPath` | `string` | Yes | Output path for the generated asset manifest |
| `contentTypes` | `Array<ContentTypeDefinition>` | No | Custom content type mappings |
| `ignoreDotFiles` | `boolean` | No | Skip files beginning with `.` |
| `ignorePaths` | `string[]` | No | Paths to exclude from the manifest |
| `ignoreWellKnown` | `boolean` | No | Skip the `.well-known/` directory |

### ContentTypeDefinition

Expand Down Expand Up @@ -189,13 +189,20 @@ If `type` is absent or does not match `'http'` or `'static'`, the build exits wi

A successful build writes a `.wasm` file to the path specified by `wasmOutput` (or `--output` in direct mode). The file is a WebAssembly Component Model component compatible with the FastEdge runtime.

On success the CLI prints:
In direct mode, on success the CLI prints:

```
Build success!!
"<input>" -> "<output>"
```

In config-driven mode, on success the CLI prints:

```
Success: Built <wasmOutput>
```

On failure it exits with a non-zero status code and prints an error message.
On failure the CLI exits with a non-zero status code and prints an error message.

## See Also

Expand Down
60 changes: 30 additions & 30 deletions docs/INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,22 @@ The FastEdge JS SDK (`@gcoredev/fastedge-sdk-js`) is the JavaScript/TypeScript d

## CLI Tools

| Tool | Command | Purpose |
| ------------------- | ------------------------------------------ | ------------------------------- |
| **fastedge-build** | `npx fastedge-build <input> <output>` | Compile JS/TS to WebAssembly |
| **fastedge-init** | `npx fastedge-init` | Interactive project scaffolding |
| **fastedge-assets** | `npx fastedge-assets <input> <output>` | Generate static asset manifest |
| Tool | Command | Purpose |
| ----------------------- | ---------------------------------------------- | ------------------------------- |
| **fastedge-build** | `npx fastedge-build <input> <output>` | Compile JS/TS to WebAssembly |
| **fastedge-init** | `npx fastedge-init` | Interactive project scaffolding |
| **fastedge-assets** | `npx fastedge-assets <input> <output>` | Generate static asset manifest |

## Documentation

| Document | Description |
| ------------------------------------ | -------------------------------------------- |
| [Quickstart](quickstart.md) | Installation and first build |
| [fastedge-build CLI](BUILD_CLI.md) | Compile JavaScript to WebAssembly |
| [fastedge-init CLI](INIT_CLI.md) | Scaffold a new FastEdge project |
| [fastedge-assets CLI](ASSETS_CLI.md) | Generate static asset manifests |
| [Static Sites](STATIC_SITES.md) | Serve static websites from WASM |
| [SDK Runtime API](SDK_API.md) | Environment, KV Store, Secrets, and Web APIs |
| Document | Description |
| -------------------------------------- | -------------------------------------------- |
| [Quickstart](quickstart.md) | Installation and first build |
| [fastedge-build CLI](BUILD_CLI.md) | Compile JavaScript to WebAssembly |
| [fastedge-init CLI](INIT_CLI.md) | Scaffold a new FastEdge project |
| [fastedge-assets CLI](ASSETS_CLI.md) | Generate static asset manifests |
| [Static Sites](STATIC_SITES.md) | Serve static websites from WASM |
| [SDK Runtime API](SDK_API.md) | Environment, KV Store, Secrets, and Web APIs |

## Application Model

Expand All @@ -49,33 +49,33 @@ addEventListener('fetch', (event) => {

## Build Types

| Type | Description | CLI |
| ---------- | ----------------------------------- | --------------------------------------------------- |
| **HTTP** | Standard request handler | `fastedge-build src/index.js output.wasm` |
| **Static** | Serve static files embedded in WASM | `fastedge-build --config .fastedge/build-config.js` |
| Type | Description | CLI |
| -------------- | ----------------------------------- | ------------------------------------------------------- |
| **HTTP** | Standard request handler | `fastedge-build src/index.js output.wasm` |
| **Static** | Serve static files embedded in WASM | `fastedge-build --config .fastedge/build-config.js` |

## Runtime APIs

Runtime APIs are available via `fastedge::` module specifiers inside your application code. These imports are resolved at compile time by the SDK.

### FastEdge APIs

| Import | Export | Signature |
| ------------------- | ---------------------- | ----------------------------------------------------- |
| `fastedge::env` | `getEnv` | `(name: string): string \| null` |
| `fastedge::secret` | `getSecret` | `(name: string): string \| null` |
| `fastedge::secret` | `getSecretEffectiveAt` | `(name: string, effectiveAt: number): string \| null` |
| `fastedge::kv` | `KvStore.open` | `(name: string): KvStoreInstance` |
| Import | Export | Signature |
| ----------------------- | -------------------------- | ------------------------------------------------------- |
| `fastedge::env` | `getEnv` | `(name: string): string \| null` |
| `fastedge::secret` | `getSecret` | `(name: string): string \| null` |
| `fastedge::secret` | `getSecretEffectiveAt` | `(name: string, effectiveAt: number): string \| null` |
| `fastedge::kv` | `KvStore.open` | `(name: string): KvStoreInstance` |

### KvStoreInstance Methods

| Method | Signature | Description |
| --------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| `get` | `(key: string): ArrayBuffer \| null` | Retrieve a value by key |
| `scan` | `(pattern: string): Array<string>` | Retrieve keys matching a prefix pattern (e.g. `foo*`) |
| `zrangeByScore` | `(key: string, min: number, max: number): Array<[ArrayBuffer, number]>` | Retrieve sorted set entries by score range |
| `zscan` | `(key: string, pattern: string): Array<[ArrayBuffer, number]>` | Retrieve sorted set entries matching a prefix pattern |
| `bfExists` | `(key: string, value: string): boolean` | Check if a value exists in a Bloom Filter |
| Method | Signature | Description |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| `get` | `(key: string): ArrayBuffer \| null` | Retrieve a value by key |
| `scan` | `(pattern: string): Array<string>` | Retrieve keys matching a prefix pattern (e.g. `foo*`) |
| `zrangeByScore` | `(key: string, min: number, max: number): Array<[ArrayBuffer, number]>` | Retrieve sorted set entries by score range |
| `zscan` | `(key: string, pattern: string): Array<[ArrayBuffer, number]>` | Retrieve sorted set entries matching a prefix pattern |
| `bfExists` | `(key: string, value: string): boolean` | Check if a value exists in a Bloom Filter |

### Web APIs

Expand Down
20 changes: 10 additions & 10 deletions docs/INIT_CLI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,16 +175,16 @@ For a SPA, `spaEntrypoint` is set to the normalized path entered at the prompt (

#### Server Config (`serverConfig`)

| Field | Type | Default | Description |
| ----------------- | ----------------- | ------------------------------ | ----------------------------------------------------- |
| `type` | `string` | `"static"` | Server type identifier |
| `extendedCache` | `string[]` | `[]` | Additional paths to serve with long cache TTLs |
| `publicDirPrefix` | `string` | `""` | URL prefix stripped before resolving asset paths |
| `compression` | `string[]` | `[]` | Compression formats (reserved for future use) |
| `notFoundPage` | `string` | `"/404.html"` | Asset path served on 404 |
| `autoExt` | `string[]` | `[]` | Extensions appended when a path has no extension |
| `autoIndex` | `string[]` | `["index.html", "index.htm"]` | Index filenames tried when resolving a directory path |
| `spaEntrypoint` | `string \| null` | `null` | Fallback asset path for unmatched routes in SPA mode |
| Field | Type | Default | Description |
| ----------------- | ---------------- | ----------------------------- | ----------------------------------------------------- |
| `type` | `string` | `"static"` | Server type identifier |
| `extendedCache` | `string[]` | `[]` | Additional paths to serve with long cache TTLs |
| `publicDirPrefix` | `string` | `""` | URL prefix stripped before resolving asset paths |
| `compression` | `string[]` | `[]` | Compression formats (reserved for future use) |
| `notFoundPage` | `string` | `"/404.html"` | Asset path served on 404 |
| `autoExt` | `string[]` | `[]` | Extensions appended when a path has no extension |
| `autoIndex` | `string[]` | `["index.html", "index.htm"]` | Index filenames tried when resolving a directory path |
| `spaEntrypoint` | `string \| null` | `null` | Fallback asset path for unmatched routes in SPA mode |

### Build Command

Expand Down
Loading
Loading