@noodleseed/agent-kit 0.1.0 → 0.2.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/manifest.json +73 -3
- package/package.json +1 -1
- package/skills/claude-code/SKILL.md +25 -26
- package/skills/claude-code/references/authoring-workflow.md +36 -0
- package/skills/claude-code/references/cli-commands.md +95 -0
- package/skills/claude-code/references/compile-errors.md +54 -0
- package/skills/claude-code/references/deploy-and-ops.md +34 -0
- package/skills/claude-code/references/examples.md +30 -0
- package/skills/claude-code/references/sdk-surface.md +39 -0
- package/skills/claude-code/references/widgets-and-apps.md +36 -0
- package/skills/codex/SKILL.md +25 -26
- package/skills/codex/references/authoring-workflow.md +36 -0
- package/skills/codex/references/cli-commands.md +95 -0
- package/skills/codex/references/compile-errors.md +54 -0
- package/skills/codex/references/deploy-and-ops.md +34 -0
- package/skills/codex/references/examples.md +30 -0
- package/skills/codex/references/sdk-surface.md +39 -0
- package/skills/codex/references/widgets-and-apps.md +36 -0
package/manifest.json
CHANGED
|
@@ -1,14 +1,84 @@
|
|
|
1
1
|
{
|
|
2
|
-
"packageVersion": "0.
|
|
2
|
+
"packageVersion": "0.2.0",
|
|
3
3
|
"files": [
|
|
4
4
|
{
|
|
5
5
|
"path": "skills/codex/SKILL.md",
|
|
6
|
-
"sha256": "
|
|
6
|
+
"sha256": "0f8af00073247aa2a188c71af64d63e54476893b5cd7e7c72ee91d59da5dbda6",
|
|
7
|
+
"agentTarget": "codex"
|
|
8
|
+
},
|
|
9
|
+
{
|
|
10
|
+
"path": "skills/codex/references/sdk-surface.md",
|
|
11
|
+
"sha256": "808225f0ae340016ee5826016770425cc83e19247cc892d4e98f76b66c067830",
|
|
12
|
+
"agentTarget": "codex"
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
"path": "skills/codex/references/cli-commands.md",
|
|
16
|
+
"sha256": "4a86f5eb39c2b9cc8016527756ee974a4c0f66d47adab0aa0f8fb02f1ae15e4d",
|
|
17
|
+
"agentTarget": "codex"
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"path": "skills/codex/references/compile-errors.md",
|
|
21
|
+
"sha256": "d1a22fb9a897714a069390d00eecfc0b4d0f87a64fdf15c94970ecb6c166dfa8",
|
|
22
|
+
"agentTarget": "codex"
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"path": "skills/codex/references/authoring-workflow.md",
|
|
26
|
+
"sha256": "85f8cbbd628e8108e813d0606edd9243441c912fa2a68fb2824663df5b738ea9",
|
|
27
|
+
"agentTarget": "codex"
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
"path": "skills/codex/references/widgets-and-apps.md",
|
|
31
|
+
"sha256": "e6b43810ca7a5f1e3e5191532557c0ac7857881b3e589448e514334fbbacbbfb",
|
|
32
|
+
"agentTarget": "codex"
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"path": "skills/codex/references/deploy-and-ops.md",
|
|
36
|
+
"sha256": "093b18c07d406763533bf6c7ccf167abf5bb981067adda5b28415ddfbacf7ae9",
|
|
37
|
+
"agentTarget": "codex"
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
"path": "skills/codex/references/examples.md",
|
|
41
|
+
"sha256": "e1871dbf9ea1dac079cd77b4f33467a99c7b03d06bc4ece30f8909398bf6d7b5",
|
|
7
42
|
"agentTarget": "codex"
|
|
8
43
|
},
|
|
9
44
|
{
|
|
10
45
|
"path": "skills/claude-code/SKILL.md",
|
|
11
|
-
"sha256": "
|
|
46
|
+
"sha256": "2eed55c064925cf533727140d7f9948aaef6a2e8e3d7ca0584d61e1fdc09fb9f",
|
|
47
|
+
"agentTarget": "claude-code"
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
"path": "skills/claude-code/references/sdk-surface.md",
|
|
51
|
+
"sha256": "808225f0ae340016ee5826016770425cc83e19247cc892d4e98f76b66c067830",
|
|
52
|
+
"agentTarget": "claude-code"
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
"path": "skills/claude-code/references/cli-commands.md",
|
|
56
|
+
"sha256": "4a86f5eb39c2b9cc8016527756ee974a4c0f66d47adab0aa0f8fb02f1ae15e4d",
|
|
57
|
+
"agentTarget": "claude-code"
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
"path": "skills/claude-code/references/compile-errors.md",
|
|
61
|
+
"sha256": "d1a22fb9a897714a069390d00eecfc0b4d0f87a64fdf15c94970ecb6c166dfa8",
|
|
62
|
+
"agentTarget": "claude-code"
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
"path": "skills/claude-code/references/authoring-workflow.md",
|
|
66
|
+
"sha256": "85f8cbbd628e8108e813d0606edd9243441c912fa2a68fb2824663df5b738ea9",
|
|
67
|
+
"agentTarget": "claude-code"
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
"path": "skills/claude-code/references/widgets-and-apps.md",
|
|
71
|
+
"sha256": "e6b43810ca7a5f1e3e5191532557c0ac7857881b3e589448e514334fbbacbbfb",
|
|
72
|
+
"agentTarget": "claude-code"
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
"path": "skills/claude-code/references/deploy-and-ops.md",
|
|
76
|
+
"sha256": "093b18c07d406763533bf6c7ccf167abf5bb981067adda5b28415ddfbacf7ae9",
|
|
77
|
+
"agentTarget": "claude-code"
|
|
78
|
+
},
|
|
79
|
+
{
|
|
80
|
+
"path": "skills/claude-code/references/examples.md",
|
|
81
|
+
"sha256": "e1871dbf9ea1dac079cd77b4f33467a99c7b03d06bc4ece30f8909398bf6d7b5",
|
|
12
82
|
"agentTarget": "claude-code"
|
|
13
83
|
}
|
|
14
84
|
]
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@noodleseed/agent-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -1,43 +1,42 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: noodle-seed
|
|
3
|
-
description: Use when building, testing, or
|
|
4
|
-
version: 0.
|
|
5
|
-
hash:
|
|
3
|
+
description: Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI.
|
|
4
|
+
version: 0.2.0
|
|
5
|
+
hash: 0d6c0f71af5c88ec
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Noodle Seed
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Build, validate, test, deploy, and operate Noodle Seed MCP servers and apps authored in TypeScript with the `noodle` CLI. Author from the configured entrypoint (usually `server.ts`); keep the authoring surface TypeScript-only.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Use this skill for project-local Noodle Seed authoring in Claude Code; preserve generated/user instruction boundaries.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Golden path
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
1. `noodle validate` — author-time compile/schema/connector check. On failure, fix the cited errors (see `references/compile-errors.md`) and re-validate; do not freeform re-edit.
|
|
17
|
+
2. `noodle test` — local compile plus a loopback MCP smoke.
|
|
18
|
+
3. `noodle dev` — local loopback runtime that serves and hot-reloads the manifest.
|
|
19
|
+
4. `noodle check` / `noodle devtools` — MCP Apps/widget readiness and preview (see `references/widgets-and-apps.md`).
|
|
20
|
+
5. `noodle deploy` after `noodle login` + `noodle link` (see `references/deploy-and-ops.md`).
|
|
17
21
|
|
|
18
|
-
|
|
19
|
-
- Local run: `noodle dev`, `noodle check`, `noodle devtools`, `noodle tools`, `noodle resources`, `noodle prompts`.
|
|
20
|
-
- Hosted: `noodle login`, `noodle logout`, `noodle whoami`, `noodle orgs`, `noodle connect`, `noodle link`, `noodle deploy`, `noodle status`, `noodle open`, `noodle access`.
|
|
21
|
-
- Config: `noodle secrets set`, `noodle variables set`, `noodle agents setup`.
|
|
22
|
+
## References
|
|
22
23
|
|
|
23
|
-
|
|
24
|
+
Load these on demand:
|
|
24
25
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
- `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.
|
|
27
|
+
- `references/cli-commands.md` — every `noodle` command, grouped by area.
|
|
28
|
+
- `references/compile-errors.md` — fix `noodle validate` errors by code.
|
|
29
|
+
- `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the validate→test→dev repair loop, connectors, and secrets/variables.
|
|
30
|
+
- `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, and CSP.
|
|
31
|
+
- `references/deploy-and-ops.md` — login/link/deploy/status/access and hosted operations.
|
|
32
|
+
- `references/examples.md` — flagship example index and a canonical `server.ts`.
|
|
28
33
|
|
|
29
|
-
##
|
|
34
|
+
## Safety
|
|
30
35
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
Use `noodle secrets set` and `noodle variables set` for runtime configuration. Keep secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle` values, and `~/.noodle/config.json` out of prompts, logs, docs, tests, and generated files. Hosted access is identity-based — do not add static data-plane credential paths.
|
|
36
|
+
- Keep secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle` values, and `~/.noodle/config.json` out of prompts, logs, docs, tests, and generated files.
|
|
37
|
+
- Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata.
|
|
38
|
+
- Do not add static data-plane credential paths; hosted access is identity-based.
|
|
36
39
|
|
|
37
40
|
## Customization
|
|
38
41
|
|
|
39
|
-
This skill is regenerated by `noodle agents setup --write`. For project-specific standards, create a separate skill; do not edit this file.
|
|
40
|
-
|
|
41
|
-
## Boundaries
|
|
42
|
-
|
|
43
|
-
Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle`, or `~/.noodle/config.json`.
|
|
42
|
+
This skill is regenerated by `noodle agents setup --write`. For project-specific standards, create a separate skill; do not edit this file or its references.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Authoring workflow
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- Input paths
|
|
6
|
+
- Repair loop
|
|
7
|
+
- Connectors
|
|
8
|
+
- Secrets and variables
|
|
9
|
+
- Boundaries
|
|
10
|
+
|
|
11
|
+
## Input paths
|
|
12
|
+
|
|
13
|
+
1. **Website scrape** — if the user gives a URL, scrape it for surface hints (products, services, hours, contact, pricing). Stop there: the URL does not reveal CRM, booking systems, custom APIs, auth model, eligibility rules, quoting logic, or approval flows. Those live in the business systems and the owner’s head — ask.
|
|
14
|
+
2. **OpenAPI import** — `noodle import openapi <file>` emits a starter `server.ts` from a spec. Use it when the user provides an OpenAPI document.
|
|
15
|
+
3. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
|
|
16
|
+
|
|
17
|
+
## Repair loop
|
|
18
|
+
|
|
19
|
+
Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile-errors.md`) → re-validate → `noodle test` → `noodle dev`. Keep the loop tight and error-driven.
|
|
20
|
+
|
|
21
|
+
## Connectors
|
|
22
|
+
|
|
23
|
+
Declare connectors as data, not imperative code:
|
|
24
|
+
|
|
25
|
+
- **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })` with per-operation `request`/`response` mapping using `${args...}` / `${response...}` expressions.
|
|
26
|
+
- **Compute**: `connector("id").version("1.0.0").compute(name, { input, output, calls?, run })` — a self-contained, sandboxed function (no imports/closure capture) that may call allowlisted operations via `callOperation`.
|
|
27
|
+
|
|
28
|
+
Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
|
|
29
|
+
|
|
30
|
+
## Secrets and variables
|
|
31
|
+
|
|
32
|
+
Author managed config as `secret("NAME")` / `variable("NAME")` and operate it with `noodle secrets set` / `noodle variables set` (scoped org/app/env). Never inline secret values in `server.ts`, tests, or generated files.
|
|
33
|
+
|
|
34
|
+
## Boundaries
|
|
35
|
+
|
|
36
|
+
Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle`, or `~/.noodle/config.json`. Hosted access is identity-based — do not add static data-plane credential paths.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# noodle CLI commands
|
|
2
|
+
|
|
3
|
+
Every `noodle` command, grouped by area. Local authoring commands (`validate`, `test`, `dev`, `tools`, `resources`, `prompts`) need no login or link.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- Authoring & validation
|
|
8
|
+
- Local run & inspect
|
|
9
|
+
- Hosted deploy & operations
|
|
10
|
+
- Org & members
|
|
11
|
+
- Managed config
|
|
12
|
+
- Governance & observability
|
|
13
|
+
- CLI maintenance
|
|
14
|
+
- Deprecated
|
|
15
|
+
|
|
16
|
+
## Authoring & validation
|
|
17
|
+
|
|
18
|
+
| Command | What it does |
|
|
19
|
+
| :-- | :-- |
|
|
20
|
+
| `noodle init` | Create a local Noodle project. |
|
|
21
|
+
| `noodle setup` | Reconcile project config and local agent files (dry-run unless `--write`). |
|
|
22
|
+
| `noodle doctor` | Check login, service, project, validation, and config. |
|
|
23
|
+
| `noodle agents` | Manage AI agent skills and project context (`setup`/`context`/`doctor`). |
|
|
24
|
+
| `noodle auth` | Diagnose `customerAuth` OIDC/bridge readiness. |
|
|
25
|
+
| `noodle docs` | Export docs in an LLM-readable format. |
|
|
26
|
+
| `noodle connect` | Print connection setup for an agent host (Claude Code, Codex, Cursor, etc.). |
|
|
27
|
+
| `noodle import` | Import an OpenAPI spec into a starter `server.ts`. |
|
|
28
|
+
| `noodle export` | Compile locally and write the portable manifest JSON (no service). |
|
|
29
|
+
| `noodle validate` | Author-time compile/schema/connector check; no service (`--json`, `--fix-prompt`). |
|
|
30
|
+
| `noodle check` | Check MCP Apps/widget readiness; no service. |
|
|
31
|
+
| `noodle test` | Local compile plus a loopback MCP smoke. |
|
|
32
|
+
|
|
33
|
+
## Local run & inspect
|
|
34
|
+
|
|
35
|
+
| Command | What it does |
|
|
36
|
+
| :-- | :-- |
|
|
37
|
+
| `noodle tools` | List local tools via a loopback MCP smoke. |
|
|
38
|
+
| `noodle resources` | List local resources via a loopback MCP smoke. |
|
|
39
|
+
| `noodle prompts` | List local prompts via a loopback MCP smoke. |
|
|
40
|
+
| `noodle dev` | Run a local loopback runtime that serves + hot-reloads the manifest (no login). |
|
|
41
|
+
| `noodle devtools` | Preview local widget metadata and rendering. |
|
|
42
|
+
|
|
43
|
+
## Hosted deploy & operations
|
|
44
|
+
|
|
45
|
+
| Command | What it does |
|
|
46
|
+
| :-- | :-- |
|
|
47
|
+
| `noodle link` | Bind this directory to a Noodle Seed Cloud target (org/app/env). |
|
|
48
|
+
| `noodle deploy` | Deploy the server to Noodle Seed Cloud. |
|
|
49
|
+
| `noodle open` | Open or print the latest deployment URL. |
|
|
50
|
+
| `noodle status` | Show hosted deployment status. |
|
|
51
|
+
| `noodle inspect` | Inspect hosted deployment metadata without secret material. |
|
|
52
|
+
| `noodle smoke` | Run hosted readiness diagnostics and print external smoke commands. |
|
|
53
|
+
| `noodle rollback` | Roll back to a previous deployment. |
|
|
54
|
+
| `noodle access` | Set the access mode (owner-only|org-members|authenticated|customers). |
|
|
55
|
+
| `noodle service` | Query hosted service capabilities. |
|
|
56
|
+
| `noodle login` | Authenticate with Noodle Seed Cloud. |
|
|
57
|
+
| `noodle logout` | Clear saved credentials. |
|
|
58
|
+
| `noodle whoami` | Print the current authenticated user. |
|
|
59
|
+
| `noodle list` | List deployments or resources for a target. |
|
|
60
|
+
| `noodle target` | Show or set the deployment target (local|cloud|other). |
|
|
61
|
+
|
|
62
|
+
## Org & members
|
|
63
|
+
|
|
64
|
+
| Command | What it does |
|
|
65
|
+
| :-- | :-- |
|
|
66
|
+
| `noodle orgs` | List or create orgs. |
|
|
67
|
+
| `noodle members` | Manage org members (list/add/remove). |
|
|
68
|
+
|
|
69
|
+
## Managed config
|
|
70
|
+
|
|
71
|
+
| Command | What it does |
|
|
72
|
+
| :-- | :-- |
|
|
73
|
+
| `noodle secrets` | Manage managed secrets (set/list/delete/resolve) by org/app/env scope. |
|
|
74
|
+
| `noodle variables` | Manage managed variables (set/list/delete/resolve) by org/app/env scope. |
|
|
75
|
+
|
|
76
|
+
## Governance & observability
|
|
77
|
+
|
|
78
|
+
| Command | What it does |
|
|
79
|
+
| :-- | :-- |
|
|
80
|
+
| `noodle audit` | Operator governance audit status and event queries. |
|
|
81
|
+
| `noodle logs` | View service/deployment logs. |
|
|
82
|
+
| `noodle policy` | Manage policy (status/list/show/effective/simulate/suspend/quota/rate/...). |
|
|
83
|
+
|
|
84
|
+
## CLI maintenance
|
|
85
|
+
|
|
86
|
+
| Command | What it does |
|
|
87
|
+
| :-- | :-- |
|
|
88
|
+
| `noodle version` | Print the installed CLI version. |
|
|
89
|
+
| `noodle update` | Show or run the global npm update command. |
|
|
90
|
+
|
|
91
|
+
## Deprecated
|
|
92
|
+
|
|
93
|
+
| Command | What it does |
|
|
94
|
+
| :-- | :-- |
|
|
95
|
+
| `noodle keys` | Removed: this command no longer exists; hosted access is identity-based. |
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Fixing noodle validate errors
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- The repair loop
|
|
6
|
+
- Error codes
|
|
7
|
+
|
|
8
|
+
## The repair loop
|
|
9
|
+
|
|
10
|
+
Run `noodle validate` (add `--json` for machine-readable output, `--fix-prompt` for an agent repair prompt). Each error carries a `code`, a dotted `path` to the offending field, and a `message`; many also carry `expected`/`got`, `didYouMean`/`suggestions`, and a `docAnchor`. Fix the specific error the `path` locates, then re-validate. Do not freeform re-edit. Once `noodle validate` passes, run `noodle test`, then `noodle dev`.
|
|
11
|
+
|
|
12
|
+
## Error codes
|
|
13
|
+
|
|
14
|
+
| Code | Fix |
|
|
15
|
+
| :-- | :-- |
|
|
16
|
+
| `yaml_parse_error` | Author in TypeScript; this means the compiled manifest was malformed — re-run from server.ts, do not hand-edit manifest data. |
|
|
17
|
+
| `invalid_shape` | A field has the wrong type or structure; match the shape the compiler reports under `path` against the SDK builder you used. |
|
|
18
|
+
| `invalid_name` | Rename the identifier to match the allowed pattern (lowercase, no spaces/reserved characters) cited at `path`. |
|
|
19
|
+
| `duplicate_name` | Two tools/components share a name; give each a unique name at the cited `path`. |
|
|
20
|
+
| `unsupported_manifest_version` | Update the SDK/CLI so the emitted manifest version is supported; do not pin an old manifest shape. |
|
|
21
|
+
| `invalid_operation_ref` | Fix the connector operation reference to `alias.operation` for an operation that exists on that connector. |
|
|
22
|
+
| `external_ref` | Remove the external/remote `$ref`; schemas must be self-contained — inline the definition instead of dereferencing a URL. |
|
|
23
|
+
| `invalid_schema_ref` | Correct the `$use` schema reference syntax at `path`; it does not name a resolvable local schema. |
|
|
24
|
+
| `unknown_schema_ref` | The `$use` target does not exist; define the referenced schema or fix the name (see `didYouMean`/`suggestions`). |
|
|
25
|
+
| `schema_ref_conflict` | Two schema references collide; rename one so a single `$use` target resolves unambiguously. |
|
|
26
|
+
| `invalid_expression` | Fix the `${...}` expression syntax at `path`; it does not parse. |
|
|
27
|
+
| `expr_unknown_root` | The expression references an unknown root; use a declared input/step/connector root (see `suggestions`). |
|
|
28
|
+
| `expr_root_unavailable` | The referenced root is not in scope at this step; reference only inputs and prior steps, never later ones. |
|
|
29
|
+
| `expr_operator_not_allowed` | Remove the disallowed operator from the expression; only the supported safe operators (e.g. `??`) are permitted. |
|
|
30
|
+
| `expr_if_not_boolean` | The `if` condition must evaluate to a boolean; adjust the expression so it yields true/false. |
|
|
31
|
+
| `unknown_step_ref` | The flow references a step id that does not exist; fix the step name (see `didYouMean`). |
|
|
32
|
+
| `forward_step_ref` | A step references a later step; reorder so each step only reads from steps recorded before it. |
|
|
33
|
+
| `self_step_ref` | A step references its own output; remove the self-reference. |
|
|
34
|
+
| `duplicate_step_id` | Two recorded steps share an id; the recorder derives ids from calls — restructure so each connector call is distinct. |
|
|
35
|
+
| `invalid_fulfilment` | The `fulfil` function records something the compiler cannot model (e.g. branching on a runtime value); record a linear sequence of connector calls and use declarative conditions. |
|
|
36
|
+
| `arg_type_mismatch` | A connector call argument has the wrong type; match the operation input type shown under `expected`/`got`. |
|
|
37
|
+
| `duplicate_resource` | Two resources share an identity; give each `resource(...)` a unique name. |
|
|
38
|
+
| `duplicate_prompt` | Two prompts share a name; rename one `prompt(...)`. |
|
|
39
|
+
| `duplicate_resource_uri` | Two resources resolve to the same URI; make each resource URI unique. |
|
|
40
|
+
| `unsupported_uri_template` | Fix the resource URI template to a supported form at the cited `path`. |
|
|
41
|
+
| `duplicate_widget` | Two widgets share an identity; give each `widget(...)`/`view` a unique component name. |
|
|
42
|
+
| `unknown_widget_tool` | The widget references a tool that does not exist; point `toolWithWidget`/`view` at a declared tool (see `didYouMean`). |
|
|
43
|
+
| `unknown_widget_action_tool` | A widget action calls a tool that is not declared; declare it or fix the action target name. |
|
|
44
|
+
| `duplicate_widget_tool` | A tool is bound to more than one widget; bind each tool to a single widget. |
|
|
45
|
+
| `invalid_widget_binding` | Fix the `data-bind`/binding expression in the widget; it does not resolve against the tool output. |
|
|
46
|
+
| `invalid_widget_state_handle` | Correct the state handle reference; declare it under `server(..., { state: { handles } })` and reference it by its declared name. |
|
|
47
|
+
| `invalid_asset` | Fix the `asset("./path")` reference; the file must exist and be a supported asset type. |
|
|
48
|
+
| `invalid_capability_requirement` | Correct the declared capability/permission requirement to a supported value. |
|
|
49
|
+
| `state_secret_field` | Remove the secret-shaped field from widget/handle state; secrets must never be stored in state or sent to widgets. |
|
|
50
|
+
| `unknown_connector_alias` | The tool calls a connector alias not declared in `use`/`provides`; add it or fix the alias (see `suggestions`). |
|
|
51
|
+
| `connector_not_in_catalog` | The referenced connector is not in the resolved catalog; add it to the project connectors or correct the reference. |
|
|
52
|
+
| `unknown_operation` | The connector has no such operation; use an operation declared on that connector (see `didYouMean`/`suggestions`). |
|
|
53
|
+
| `unused_connector_alias` | A declared connector alias is never called; remove the unused `use` entry or wire it into a tool. |
|
|
54
|
+
| `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Deploy and operations
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- Authenticate
|
|
6
|
+
- Link and target
|
|
7
|
+
- Deploy and inspect
|
|
8
|
+
- Access modes
|
|
9
|
+
- Org and members
|
|
10
|
+
- Config and observability
|
|
11
|
+
|
|
12
|
+
## Authenticate
|
|
13
|
+
|
|
14
|
+
`noodle login` to authenticate with Noodle Seed Cloud, `noodle whoami` to confirm, `noodle logout` to clear credentials. Local commands (`dev`/`validate`/`test`) need none of this.
|
|
15
|
+
|
|
16
|
+
## Link and target
|
|
17
|
+
|
|
18
|
+
`noodle link --org <slug> --app <slug> [--env <slug>]` binds the directory to a target. Unlinked, `noodle deploy` uses your default org, the project name as the app, and `prod`. `noodle target show|set` inspects or changes the target.
|
|
19
|
+
|
|
20
|
+
## Deploy and inspect
|
|
21
|
+
|
|
22
|
+
`noodle deploy` deploys the server. Then `noodle open` (latest URL), `noodle status`, `noodle inspect` (metadata, no secrets), `noodle smoke` (readiness diagnostics), and `noodle rollback <deploymentId>` to revert.
|
|
23
|
+
|
|
24
|
+
## Access modes
|
|
25
|
+
|
|
26
|
+
`noodle access set owner-only|org-members|authenticated|customers` controls who can call the deployed server. Hosted access is identity-based; never add static data-plane keys.
|
|
27
|
+
|
|
28
|
+
## Org and members
|
|
29
|
+
|
|
30
|
+
`noodle orgs list|create` and `noodle members list|add|remove --org <slug>` manage organizations and membership.
|
|
31
|
+
|
|
32
|
+
## Config and observability
|
|
33
|
+
|
|
34
|
+
Manage runtime config with `noodle secrets` / `noodle variables` (scoped org/app/env). Operators use `noodle logs`, `noodle audit`, and `noodle policy` for logs, governance audit, and policy.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Examples
|
|
2
|
+
|
|
3
|
+
Flagship examples (one per capability). Read the matching example for the pattern you need; extend an existing flagship rather than inventing a new shape.
|
|
4
|
+
|
|
5
|
+
| Example | Use when |
|
|
6
|
+
| :-- | :-- |
|
|
7
|
+
| `hello` | Minimal TypeScript quickstart — a single tool, no connectors/widgets. |
|
|
8
|
+
| `weather` | HTTP connectors, multi-step flows, and the sandboxed compute connector. |
|
|
9
|
+
| `restaurant-pickup` | MCP Apps widgets, React `view` authoring, assets, branding, and handoff. |
|
|
10
|
+
| `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. |
|
|
11
|
+
| `stateful-draft` | Durable, caller-scoped widget state handles with optimistic revisions. |
|
|
12
|
+
| `perplexity` | A real SaaS API with bearer auth and a managed `secret`. |
|
|
13
|
+
| `internal-ops-demo` | Governed internal connectivity — tools/resources/prompts, role-shaped output. |
|
|
14
|
+
|
|
15
|
+
## Canonical server.ts
|
|
16
|
+
|
|
17
|
+
Author with `server(name, options, definitions)` and top-level helpers:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { server, tool, z } from '@noodleseed/one';
|
|
21
|
+
|
|
22
|
+
export default server('hello', { title: 'Hello', version: '1.0.0' }, [
|
|
23
|
+
tool('greet', {
|
|
24
|
+
description: 'Greet someone by name.',
|
|
25
|
+
input: z.object({ name: z.string() }),
|
|
26
|
+
output: z.object({ greeting: z.string() }),
|
|
27
|
+
fulfil: ({ input }) => ({ greeting: `Hello, ${input.name}!` }),
|
|
28
|
+
}),
|
|
29
|
+
]);
|
|
30
|
+
```
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# @noodleseed/one SDK surface
|
|
2
|
+
|
|
3
|
+
Import these from `@noodleseed/one`. They are declarative builders that emit manifest data — do not hand-author the manifest or runtime artifacts. React view helpers come from `@noodleseed/one/react` (`generateHelpers`).
|
|
4
|
+
|
|
5
|
+
## Server & tools
|
|
6
|
+
|
|
7
|
+
- `server(name, options, definitions)` — the server/app root.
|
|
8
|
+
- `tool(name, { description, input, output, fulfil })` — a model-visible tool.
|
|
9
|
+
- `toolWithWidget(name, { ..., view })` — a model-visible tool that renders an MCP Apps widget.
|
|
10
|
+
- `toolForWidget(name, { ... })` — a widget-only helper tool, hidden from the model.
|
|
11
|
+
|
|
12
|
+
## Widgets & assets
|
|
13
|
+
|
|
14
|
+
- `widget(...)` — declare a widget/view component.
|
|
15
|
+
- `asset("./path")` — reference a packaged asset (e.g. an image).
|
|
16
|
+
- `annotations(...)` — tool/Apps annotation metadata.
|
|
17
|
+
|
|
18
|
+
## Connectors & flows
|
|
19
|
+
|
|
20
|
+
- `connector("id").version(...).http({...})` or `.compute(...)` — declarative data connectors.
|
|
21
|
+
- `when(...)` — declarative conditions for recorded flows (no native branching on runtime values).
|
|
22
|
+
|
|
23
|
+
## Resources & prompts
|
|
24
|
+
|
|
25
|
+
- `resource(name, { ... })` — an MCP resource.
|
|
26
|
+
- `prompt(name, { ... })` — an MCP prompt.
|
|
27
|
+
|
|
28
|
+
## Managed config
|
|
29
|
+
|
|
30
|
+
- `secret("NAME")` — reference a managed secret (operated via `noodle secrets`).
|
|
31
|
+
- `variable("NAME")` — reference a managed variable (operated via `noodle variables`).
|
|
32
|
+
|
|
33
|
+
## Sessions
|
|
34
|
+
|
|
35
|
+
- `handoffSession(...)` — typed cross-host handoff session envelopes.
|
|
36
|
+
|
|
37
|
+
## Schemas
|
|
38
|
+
|
|
39
|
+
- `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# MCP Apps and widgets
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- Tools and views
|
|
6
|
+
- React authoring
|
|
7
|
+
- CSP and permissions
|
|
8
|
+
- Host bridge
|
|
9
|
+
- Readiness and boundaries
|
|
10
|
+
|
|
11
|
+
## Tools and views
|
|
12
|
+
|
|
13
|
+
Use `toolWithWidget(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and `toolForWidget(name, { ... })` for a widget-only helper hidden from the model. A `view` is `{ component: "name", entry: "./views/name.tsx" }`.
|
|
14
|
+
|
|
15
|
+
## React authoring
|
|
16
|
+
|
|
17
|
+
Author views as React components. Get typed helpers from `@noodleseed/one/react`:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { generateHelpers } from '@noodleseed/one/react';
|
|
21
|
+
const { useCallTool, useLayout, useToolInfo, useViewState } = generateHelpers<AppType>();
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Bind interactive elements to tools (`useCallTool("place_order")`) and annotate model-facing context with `data-llm`. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`).
|
|
25
|
+
|
|
26
|
+
## CSP and permissions
|
|
27
|
+
|
|
28
|
+
Declare network/host needs explicitly: `csp: { connectDomains, resourceDomains, frameDomains }` and `permissions` (e.g. `clipboardWrite`). Secrets are never injected into widgets; tool output is redacted before widget delivery.
|
|
29
|
+
|
|
30
|
+
## Host bridge
|
|
31
|
+
|
|
32
|
+
One runtime targets both Claude’s ext-apps bridge and ChatGPT’s `window.openai`, detected at startup. Tool results still carry useful `content`/`structuredContent` so non-Apps hosts degrade gracefully.
|
|
33
|
+
|
|
34
|
+
## Readiness and boundaries
|
|
35
|
+
|
|
36
|
+
Run `noodle check` for widget/Apps readiness and `noodle devtools` to preview metadata and rendering. Brand via the `server` `branding` tokens (the compiler derives the palette); do not inject raw global CSS.
|
package/skills/codex/SKILL.md
CHANGED
|
@@ -1,43 +1,42 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: noodle-seed
|
|
3
|
-
description: Use when building, testing, or
|
|
4
|
-
version: 0.
|
|
5
|
-
hash:
|
|
3
|
+
description: Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI.
|
|
4
|
+
version: 0.2.0
|
|
5
|
+
hash: f297c7e0fa62058d
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Noodle Seed
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Build, validate, test, deploy, and operate Noodle Seed MCP servers and apps authored in TypeScript with the `noodle` CLI. Author from the configured entrypoint (usually `server.ts`); keep the authoring surface TypeScript-only.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Use this skill for local Noodle Seed project work in Codex.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Golden path
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
1. `noodle validate` — author-time compile/schema/connector check. On failure, fix the cited errors (see `references/compile-errors.md`) and re-validate; do not freeform re-edit.
|
|
17
|
+
2. `noodle test` — local compile plus a loopback MCP smoke.
|
|
18
|
+
3. `noodle dev` — local loopback runtime that serves and hot-reloads the manifest.
|
|
19
|
+
4. `noodle check` / `noodle devtools` — MCP Apps/widget readiness and preview (see `references/widgets-and-apps.md`).
|
|
20
|
+
5. `noodle deploy` after `noodle login` + `noodle link` (see `references/deploy-and-ops.md`).
|
|
17
21
|
|
|
18
|
-
|
|
19
|
-
- Local run: `noodle dev`, `noodle check`, `noodle devtools`, `noodle tools`, `noodle resources`, `noodle prompts`.
|
|
20
|
-
- Hosted: `noodle login`, `noodle logout`, `noodle whoami`, `noodle orgs`, `noodle connect`, `noodle link`, `noodle deploy`, `noodle status`, `noodle open`, `noodle access`.
|
|
21
|
-
- Config: `noodle secrets set`, `noodle variables set`, `noodle agents setup`.
|
|
22
|
+
## References
|
|
22
23
|
|
|
23
|
-
|
|
24
|
+
Load these on demand:
|
|
24
25
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
- `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.
|
|
27
|
+
- `references/cli-commands.md` — every `noodle` command, grouped by area.
|
|
28
|
+
- `references/compile-errors.md` — fix `noodle validate` errors by code.
|
|
29
|
+
- `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the validate→test→dev repair loop, connectors, and secrets/variables.
|
|
30
|
+
- `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, and CSP.
|
|
31
|
+
- `references/deploy-and-ops.md` — login/link/deploy/status/access and hosted operations.
|
|
32
|
+
- `references/examples.md` — flagship example index and a canonical `server.ts`.
|
|
28
33
|
|
|
29
|
-
##
|
|
34
|
+
## Safety
|
|
30
35
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
Use `noodle secrets set` and `noodle variables set` for runtime configuration. Keep secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle` values, and `~/.noodle/config.json` out of prompts, logs, docs, tests, and generated files. Hosted access is identity-based — do not add static data-plane credential paths.
|
|
36
|
+
- Keep secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle` values, and `~/.noodle/config.json` out of prompts, logs, docs, tests, and generated files.
|
|
37
|
+
- Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata.
|
|
38
|
+
- Do not add static data-plane credential paths; hosted access is identity-based.
|
|
36
39
|
|
|
37
40
|
## Customization
|
|
38
41
|
|
|
39
|
-
This skill is regenerated by `noodle agents setup --write`. For project-specific standards, create a separate skill; do not edit this file.
|
|
40
|
-
|
|
41
|
-
## Boundaries
|
|
42
|
-
|
|
43
|
-
Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle`, or `~/.noodle/config.json`.
|
|
42
|
+
This skill is regenerated by `noodle agents setup --write`. For project-specific standards, create a separate skill; do not edit this file or its references.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Authoring workflow
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- Input paths
|
|
6
|
+
- Repair loop
|
|
7
|
+
- Connectors
|
|
8
|
+
- Secrets and variables
|
|
9
|
+
- Boundaries
|
|
10
|
+
|
|
11
|
+
## Input paths
|
|
12
|
+
|
|
13
|
+
1. **Website scrape** — if the user gives a URL, scrape it for surface hints (products, services, hours, contact, pricing). Stop there: the URL does not reveal CRM, booking systems, custom APIs, auth model, eligibility rules, quoting logic, or approval flows. Those live in the business systems and the owner’s head — ask.
|
|
14
|
+
2. **OpenAPI import** — `noodle import openapi <file>` emits a starter `server.ts` from a spec. Use it when the user provides an OpenAPI document.
|
|
15
|
+
3. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
|
|
16
|
+
|
|
17
|
+
## Repair loop
|
|
18
|
+
|
|
19
|
+
Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile-errors.md`) → re-validate → `noodle test` → `noodle dev`. Keep the loop tight and error-driven.
|
|
20
|
+
|
|
21
|
+
## Connectors
|
|
22
|
+
|
|
23
|
+
Declare connectors as data, not imperative code:
|
|
24
|
+
|
|
25
|
+
- **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })` with per-operation `request`/`response` mapping using `${args...}` / `${response...}` expressions.
|
|
26
|
+
- **Compute**: `connector("id").version("1.0.0").compute(name, { input, output, calls?, run })` — a self-contained, sandboxed function (no imports/closure capture) that may call allowlisted operations via `callOperation`.
|
|
27
|
+
|
|
28
|
+
Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
|
|
29
|
+
|
|
30
|
+
## Secrets and variables
|
|
31
|
+
|
|
32
|
+
Author managed config as `secret("NAME")` / `variable("NAME")` and operate it with `noodle secrets set` / `noodle variables set` (scoped org/app/env). Never inline secret values in `server.ts`, tests, or generated files.
|
|
33
|
+
|
|
34
|
+
## Boundaries
|
|
35
|
+
|
|
36
|
+
Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle`, or `~/.noodle/config.json`. Hosted access is identity-based — do not add static data-plane credential paths.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# noodle CLI commands
|
|
2
|
+
|
|
3
|
+
Every `noodle` command, grouped by area. Local authoring commands (`validate`, `test`, `dev`, `tools`, `resources`, `prompts`) need no login or link.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- Authoring & validation
|
|
8
|
+
- Local run & inspect
|
|
9
|
+
- Hosted deploy & operations
|
|
10
|
+
- Org & members
|
|
11
|
+
- Managed config
|
|
12
|
+
- Governance & observability
|
|
13
|
+
- CLI maintenance
|
|
14
|
+
- Deprecated
|
|
15
|
+
|
|
16
|
+
## Authoring & validation
|
|
17
|
+
|
|
18
|
+
| Command | What it does |
|
|
19
|
+
| :-- | :-- |
|
|
20
|
+
| `noodle init` | Create a local Noodle project. |
|
|
21
|
+
| `noodle setup` | Reconcile project config and local agent files (dry-run unless `--write`). |
|
|
22
|
+
| `noodle doctor` | Check login, service, project, validation, and config. |
|
|
23
|
+
| `noodle agents` | Manage AI agent skills and project context (`setup`/`context`/`doctor`). |
|
|
24
|
+
| `noodle auth` | Diagnose `customerAuth` OIDC/bridge readiness. |
|
|
25
|
+
| `noodle docs` | Export docs in an LLM-readable format. |
|
|
26
|
+
| `noodle connect` | Print connection setup for an agent host (Claude Code, Codex, Cursor, etc.). |
|
|
27
|
+
| `noodle import` | Import an OpenAPI spec into a starter `server.ts`. |
|
|
28
|
+
| `noodle export` | Compile locally and write the portable manifest JSON (no service). |
|
|
29
|
+
| `noodle validate` | Author-time compile/schema/connector check; no service (`--json`, `--fix-prompt`). |
|
|
30
|
+
| `noodle check` | Check MCP Apps/widget readiness; no service. |
|
|
31
|
+
| `noodle test` | Local compile plus a loopback MCP smoke. |
|
|
32
|
+
|
|
33
|
+
## Local run & inspect
|
|
34
|
+
|
|
35
|
+
| Command | What it does |
|
|
36
|
+
| :-- | :-- |
|
|
37
|
+
| `noodle tools` | List local tools via a loopback MCP smoke. |
|
|
38
|
+
| `noodle resources` | List local resources via a loopback MCP smoke. |
|
|
39
|
+
| `noodle prompts` | List local prompts via a loopback MCP smoke. |
|
|
40
|
+
| `noodle dev` | Run a local loopback runtime that serves + hot-reloads the manifest (no login). |
|
|
41
|
+
| `noodle devtools` | Preview local widget metadata and rendering. |
|
|
42
|
+
|
|
43
|
+
## Hosted deploy & operations
|
|
44
|
+
|
|
45
|
+
| Command | What it does |
|
|
46
|
+
| :-- | :-- |
|
|
47
|
+
| `noodle link` | Bind this directory to a Noodle Seed Cloud target (org/app/env). |
|
|
48
|
+
| `noodle deploy` | Deploy the server to Noodle Seed Cloud. |
|
|
49
|
+
| `noodle open` | Open or print the latest deployment URL. |
|
|
50
|
+
| `noodle status` | Show hosted deployment status. |
|
|
51
|
+
| `noodle inspect` | Inspect hosted deployment metadata without secret material. |
|
|
52
|
+
| `noodle smoke` | Run hosted readiness diagnostics and print external smoke commands. |
|
|
53
|
+
| `noodle rollback` | Roll back to a previous deployment. |
|
|
54
|
+
| `noodle access` | Set the access mode (owner-only|org-members|authenticated|customers). |
|
|
55
|
+
| `noodle service` | Query hosted service capabilities. |
|
|
56
|
+
| `noodle login` | Authenticate with Noodle Seed Cloud. |
|
|
57
|
+
| `noodle logout` | Clear saved credentials. |
|
|
58
|
+
| `noodle whoami` | Print the current authenticated user. |
|
|
59
|
+
| `noodle list` | List deployments or resources for a target. |
|
|
60
|
+
| `noodle target` | Show or set the deployment target (local|cloud|other). |
|
|
61
|
+
|
|
62
|
+
## Org & members
|
|
63
|
+
|
|
64
|
+
| Command | What it does |
|
|
65
|
+
| :-- | :-- |
|
|
66
|
+
| `noodle orgs` | List or create orgs. |
|
|
67
|
+
| `noodle members` | Manage org members (list/add/remove). |
|
|
68
|
+
|
|
69
|
+
## Managed config
|
|
70
|
+
|
|
71
|
+
| Command | What it does |
|
|
72
|
+
| :-- | :-- |
|
|
73
|
+
| `noodle secrets` | Manage managed secrets (set/list/delete/resolve) by org/app/env scope. |
|
|
74
|
+
| `noodle variables` | Manage managed variables (set/list/delete/resolve) by org/app/env scope. |
|
|
75
|
+
|
|
76
|
+
## Governance & observability
|
|
77
|
+
|
|
78
|
+
| Command | What it does |
|
|
79
|
+
| :-- | :-- |
|
|
80
|
+
| `noodle audit` | Operator governance audit status and event queries. |
|
|
81
|
+
| `noodle logs` | View service/deployment logs. |
|
|
82
|
+
| `noodle policy` | Manage policy (status/list/show/effective/simulate/suspend/quota/rate/...). |
|
|
83
|
+
|
|
84
|
+
## CLI maintenance
|
|
85
|
+
|
|
86
|
+
| Command | What it does |
|
|
87
|
+
| :-- | :-- |
|
|
88
|
+
| `noodle version` | Print the installed CLI version. |
|
|
89
|
+
| `noodle update` | Show or run the global npm update command. |
|
|
90
|
+
|
|
91
|
+
## Deprecated
|
|
92
|
+
|
|
93
|
+
| Command | What it does |
|
|
94
|
+
| :-- | :-- |
|
|
95
|
+
| `noodle keys` | Removed: this command no longer exists; hosted access is identity-based. |
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Fixing noodle validate errors
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- The repair loop
|
|
6
|
+
- Error codes
|
|
7
|
+
|
|
8
|
+
## The repair loop
|
|
9
|
+
|
|
10
|
+
Run `noodle validate` (add `--json` for machine-readable output, `--fix-prompt` for an agent repair prompt). Each error carries a `code`, a dotted `path` to the offending field, and a `message`; many also carry `expected`/`got`, `didYouMean`/`suggestions`, and a `docAnchor`. Fix the specific error the `path` locates, then re-validate. Do not freeform re-edit. Once `noodle validate` passes, run `noodle test`, then `noodle dev`.
|
|
11
|
+
|
|
12
|
+
## Error codes
|
|
13
|
+
|
|
14
|
+
| Code | Fix |
|
|
15
|
+
| :-- | :-- |
|
|
16
|
+
| `yaml_parse_error` | Author in TypeScript; this means the compiled manifest was malformed — re-run from server.ts, do not hand-edit manifest data. |
|
|
17
|
+
| `invalid_shape` | A field has the wrong type or structure; match the shape the compiler reports under `path` against the SDK builder you used. |
|
|
18
|
+
| `invalid_name` | Rename the identifier to match the allowed pattern (lowercase, no spaces/reserved characters) cited at `path`. |
|
|
19
|
+
| `duplicate_name` | Two tools/components share a name; give each a unique name at the cited `path`. |
|
|
20
|
+
| `unsupported_manifest_version` | Update the SDK/CLI so the emitted manifest version is supported; do not pin an old manifest shape. |
|
|
21
|
+
| `invalid_operation_ref` | Fix the connector operation reference to `alias.operation` for an operation that exists on that connector. |
|
|
22
|
+
| `external_ref` | Remove the external/remote `$ref`; schemas must be self-contained — inline the definition instead of dereferencing a URL. |
|
|
23
|
+
| `invalid_schema_ref` | Correct the `$use` schema reference syntax at `path`; it does not name a resolvable local schema. |
|
|
24
|
+
| `unknown_schema_ref` | The `$use` target does not exist; define the referenced schema or fix the name (see `didYouMean`/`suggestions`). |
|
|
25
|
+
| `schema_ref_conflict` | Two schema references collide; rename one so a single `$use` target resolves unambiguously. |
|
|
26
|
+
| `invalid_expression` | Fix the `${...}` expression syntax at `path`; it does not parse. |
|
|
27
|
+
| `expr_unknown_root` | The expression references an unknown root; use a declared input/step/connector root (see `suggestions`). |
|
|
28
|
+
| `expr_root_unavailable` | The referenced root is not in scope at this step; reference only inputs and prior steps, never later ones. |
|
|
29
|
+
| `expr_operator_not_allowed` | Remove the disallowed operator from the expression; only the supported safe operators (e.g. `??`) are permitted. |
|
|
30
|
+
| `expr_if_not_boolean` | The `if` condition must evaluate to a boolean; adjust the expression so it yields true/false. |
|
|
31
|
+
| `unknown_step_ref` | The flow references a step id that does not exist; fix the step name (see `didYouMean`). |
|
|
32
|
+
| `forward_step_ref` | A step references a later step; reorder so each step only reads from steps recorded before it. |
|
|
33
|
+
| `self_step_ref` | A step references its own output; remove the self-reference. |
|
|
34
|
+
| `duplicate_step_id` | Two recorded steps share an id; the recorder derives ids from calls — restructure so each connector call is distinct. |
|
|
35
|
+
| `invalid_fulfilment` | The `fulfil` function records something the compiler cannot model (e.g. branching on a runtime value); record a linear sequence of connector calls and use declarative conditions. |
|
|
36
|
+
| `arg_type_mismatch` | A connector call argument has the wrong type; match the operation input type shown under `expected`/`got`. |
|
|
37
|
+
| `duplicate_resource` | Two resources share an identity; give each `resource(...)` a unique name. |
|
|
38
|
+
| `duplicate_prompt` | Two prompts share a name; rename one `prompt(...)`. |
|
|
39
|
+
| `duplicate_resource_uri` | Two resources resolve to the same URI; make each resource URI unique. |
|
|
40
|
+
| `unsupported_uri_template` | Fix the resource URI template to a supported form at the cited `path`. |
|
|
41
|
+
| `duplicate_widget` | Two widgets share an identity; give each `widget(...)`/`view` a unique component name. |
|
|
42
|
+
| `unknown_widget_tool` | The widget references a tool that does not exist; point `toolWithWidget`/`view` at a declared tool (see `didYouMean`). |
|
|
43
|
+
| `unknown_widget_action_tool` | A widget action calls a tool that is not declared; declare it or fix the action target name. |
|
|
44
|
+
| `duplicate_widget_tool` | A tool is bound to more than one widget; bind each tool to a single widget. |
|
|
45
|
+
| `invalid_widget_binding` | Fix the `data-bind`/binding expression in the widget; it does not resolve against the tool output. |
|
|
46
|
+
| `invalid_widget_state_handle` | Correct the state handle reference; declare it under `server(..., { state: { handles } })` and reference it by its declared name. |
|
|
47
|
+
| `invalid_asset` | Fix the `asset("./path")` reference; the file must exist and be a supported asset type. |
|
|
48
|
+
| `invalid_capability_requirement` | Correct the declared capability/permission requirement to a supported value. |
|
|
49
|
+
| `state_secret_field` | Remove the secret-shaped field from widget/handle state; secrets must never be stored in state or sent to widgets. |
|
|
50
|
+
| `unknown_connector_alias` | The tool calls a connector alias not declared in `use`/`provides`; add it or fix the alias (see `suggestions`). |
|
|
51
|
+
| `connector_not_in_catalog` | The referenced connector is not in the resolved catalog; add it to the project connectors or correct the reference. |
|
|
52
|
+
| `unknown_operation` | The connector has no such operation; use an operation declared on that connector (see `didYouMean`/`suggestions`). |
|
|
53
|
+
| `unused_connector_alias` | A declared connector alias is never called; remove the unused `use` entry or wire it into a tool. |
|
|
54
|
+
| `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Deploy and operations
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- Authenticate
|
|
6
|
+
- Link and target
|
|
7
|
+
- Deploy and inspect
|
|
8
|
+
- Access modes
|
|
9
|
+
- Org and members
|
|
10
|
+
- Config and observability
|
|
11
|
+
|
|
12
|
+
## Authenticate
|
|
13
|
+
|
|
14
|
+
`noodle login` to authenticate with Noodle Seed Cloud, `noodle whoami` to confirm, `noodle logout` to clear credentials. Local commands (`dev`/`validate`/`test`) need none of this.
|
|
15
|
+
|
|
16
|
+
## Link and target
|
|
17
|
+
|
|
18
|
+
`noodle link --org <slug> --app <slug> [--env <slug>]` binds the directory to a target. Unlinked, `noodle deploy` uses your default org, the project name as the app, and `prod`. `noodle target show|set` inspects or changes the target.
|
|
19
|
+
|
|
20
|
+
## Deploy and inspect
|
|
21
|
+
|
|
22
|
+
`noodle deploy` deploys the server. Then `noodle open` (latest URL), `noodle status`, `noodle inspect` (metadata, no secrets), `noodle smoke` (readiness diagnostics), and `noodle rollback <deploymentId>` to revert.
|
|
23
|
+
|
|
24
|
+
## Access modes
|
|
25
|
+
|
|
26
|
+
`noodle access set owner-only|org-members|authenticated|customers` controls who can call the deployed server. Hosted access is identity-based; never add static data-plane keys.
|
|
27
|
+
|
|
28
|
+
## Org and members
|
|
29
|
+
|
|
30
|
+
`noodle orgs list|create` and `noodle members list|add|remove --org <slug>` manage organizations and membership.
|
|
31
|
+
|
|
32
|
+
## Config and observability
|
|
33
|
+
|
|
34
|
+
Manage runtime config with `noodle secrets` / `noodle variables` (scoped org/app/env). Operators use `noodle logs`, `noodle audit`, and `noodle policy` for logs, governance audit, and policy.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Examples
|
|
2
|
+
|
|
3
|
+
Flagship examples (one per capability). Read the matching example for the pattern you need; extend an existing flagship rather than inventing a new shape.
|
|
4
|
+
|
|
5
|
+
| Example | Use when |
|
|
6
|
+
| :-- | :-- |
|
|
7
|
+
| `hello` | Minimal TypeScript quickstart — a single tool, no connectors/widgets. |
|
|
8
|
+
| `weather` | HTTP connectors, multi-step flows, and the sandboxed compute connector. |
|
|
9
|
+
| `restaurant-pickup` | MCP Apps widgets, React `view` authoring, assets, branding, and handoff. |
|
|
10
|
+
| `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. |
|
|
11
|
+
| `stateful-draft` | Durable, caller-scoped widget state handles with optimistic revisions. |
|
|
12
|
+
| `perplexity` | A real SaaS API with bearer auth and a managed `secret`. |
|
|
13
|
+
| `internal-ops-demo` | Governed internal connectivity — tools/resources/prompts, role-shaped output. |
|
|
14
|
+
|
|
15
|
+
## Canonical server.ts
|
|
16
|
+
|
|
17
|
+
Author with `server(name, options, definitions)` and top-level helpers:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { server, tool, z } from '@noodleseed/one';
|
|
21
|
+
|
|
22
|
+
export default server('hello', { title: 'Hello', version: '1.0.0' }, [
|
|
23
|
+
tool('greet', {
|
|
24
|
+
description: 'Greet someone by name.',
|
|
25
|
+
input: z.object({ name: z.string() }),
|
|
26
|
+
output: z.object({ greeting: z.string() }),
|
|
27
|
+
fulfil: ({ input }) => ({ greeting: `Hello, ${input.name}!` }),
|
|
28
|
+
}),
|
|
29
|
+
]);
|
|
30
|
+
```
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# @noodleseed/one SDK surface
|
|
2
|
+
|
|
3
|
+
Import these from `@noodleseed/one`. They are declarative builders that emit manifest data — do not hand-author the manifest or runtime artifacts. React view helpers come from `@noodleseed/one/react` (`generateHelpers`).
|
|
4
|
+
|
|
5
|
+
## Server & tools
|
|
6
|
+
|
|
7
|
+
- `server(name, options, definitions)` — the server/app root.
|
|
8
|
+
- `tool(name, { description, input, output, fulfil })` — a model-visible tool.
|
|
9
|
+
- `toolWithWidget(name, { ..., view })` — a model-visible tool that renders an MCP Apps widget.
|
|
10
|
+
- `toolForWidget(name, { ... })` — a widget-only helper tool, hidden from the model.
|
|
11
|
+
|
|
12
|
+
## Widgets & assets
|
|
13
|
+
|
|
14
|
+
- `widget(...)` — declare a widget/view component.
|
|
15
|
+
- `asset("./path")` — reference a packaged asset (e.g. an image).
|
|
16
|
+
- `annotations(...)` — tool/Apps annotation metadata.
|
|
17
|
+
|
|
18
|
+
## Connectors & flows
|
|
19
|
+
|
|
20
|
+
- `connector("id").version(...).http({...})` or `.compute(...)` — declarative data connectors.
|
|
21
|
+
- `when(...)` — declarative conditions for recorded flows (no native branching on runtime values).
|
|
22
|
+
|
|
23
|
+
## Resources & prompts
|
|
24
|
+
|
|
25
|
+
- `resource(name, { ... })` — an MCP resource.
|
|
26
|
+
- `prompt(name, { ... })` — an MCP prompt.
|
|
27
|
+
|
|
28
|
+
## Managed config
|
|
29
|
+
|
|
30
|
+
- `secret("NAME")` — reference a managed secret (operated via `noodle secrets`).
|
|
31
|
+
- `variable("NAME")` — reference a managed variable (operated via `noodle variables`).
|
|
32
|
+
|
|
33
|
+
## Sessions
|
|
34
|
+
|
|
35
|
+
- `handoffSession(...)` — typed cross-host handoff session envelopes.
|
|
36
|
+
|
|
37
|
+
## Schemas
|
|
38
|
+
|
|
39
|
+
- `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# MCP Apps and widgets
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- Tools and views
|
|
6
|
+
- React authoring
|
|
7
|
+
- CSP and permissions
|
|
8
|
+
- Host bridge
|
|
9
|
+
- Readiness and boundaries
|
|
10
|
+
|
|
11
|
+
## Tools and views
|
|
12
|
+
|
|
13
|
+
Use `toolWithWidget(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and `toolForWidget(name, { ... })` for a widget-only helper hidden from the model. A `view` is `{ component: "name", entry: "./views/name.tsx" }`.
|
|
14
|
+
|
|
15
|
+
## React authoring
|
|
16
|
+
|
|
17
|
+
Author views as React components. Get typed helpers from `@noodleseed/one/react`:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { generateHelpers } from '@noodleseed/one/react';
|
|
21
|
+
const { useCallTool, useLayout, useToolInfo, useViewState } = generateHelpers<AppType>();
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Bind interactive elements to tools (`useCallTool("place_order")`) and annotate model-facing context with `data-llm`. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`).
|
|
25
|
+
|
|
26
|
+
## CSP and permissions
|
|
27
|
+
|
|
28
|
+
Declare network/host needs explicitly: `csp: { connectDomains, resourceDomains, frameDomains }` and `permissions` (e.g. `clipboardWrite`). Secrets are never injected into widgets; tool output is redacted before widget delivery.
|
|
29
|
+
|
|
30
|
+
## Host bridge
|
|
31
|
+
|
|
32
|
+
One runtime targets both Claude’s ext-apps bridge and ChatGPT’s `window.openai`, detected at startup. Tool results still carry useful `content`/`structuredContent` so non-Apps hosts degrade gracefully.
|
|
33
|
+
|
|
34
|
+
## Readiness and boundaries
|
|
35
|
+
|
|
36
|
+
Run `noodle check` for widget/Apps readiness and `noodle devtools` to preview metadata and rendering. Brand via the `server` `branding` tokens (the compiler derives the palette); do not inject raw global CSS.
|