npm - create-ampless - Versions diffs - 1.0.0-alpha.78 → 1.0.0-alpha.80 - Mend

create-ampless 1.0.0-alpha.78 → 1.0.0-alpha.80

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.

Files changed (17) hide show

package/dist/index.js +411 -32
package/dist/templates/_shared/docs/plugin-author-guide.ja.md +258 -12
package/dist/templates/_shared/docs/plugin-author-guide.md +337 -20
package/dist/templates/_shared/package.json +12 -12
package/dist/templates/_shared/plugins/README.ja.md +30 -6
package/dist/templates/_shared/plugins/README.md +32 -6
package/dist/templates/plugin-local/README.md +34 -0
package/dist/templates/plugin-local/index.ts +39 -0
package/dist/templates/plugin-standalone/CHANGELOG.md +1 -0
package/dist/templates/plugin-standalone/README.ja.md +43 -0
package/dist/templates/plugin-standalone/README.md +43 -0
package/dist/templates/plugin-standalone/package.json +47 -0
package/dist/templates/plugin-standalone/src/index.test.ts +16 -0
package/dist/templates/plugin-standalone/src/index.ts +29 -0
package/dist/templates/plugin-standalone/tsconfig.json +16 -0
package/dist/templates/plugin-standalone/tsup.config.ts +8 -0
package/package.json +1 -1

package/dist/templates/_shared/docs/plugin-author-guide.md CHANGED Viewed

@@ -21,8 +21,62 @@ this page is the hands-on companion.
 ---
+## 0. Theme vs Plugin Boundary
+ampless ships both themes and plugins. Picking the right tool keeps
+your code where future-you (and other site authors) will look for it.
+| Want to change... | Use a theme | Use a plugin |
+|---|---|---|
+| Layout, typography, colour, per-route UI | ✓ | |
+| Custom components on home / post / tag pages | ✓ | |
+| Admin-editable settings exposed to non-developers | | ✓ (`adminSettings`) |
+| Background work after content events (RSS, search index, webhooks) | | ✓ (`eventHooks`) |
+| Trusted side effects (S3 writes, external API push) | | ✓ (`writePublicAsset` + `trusted`) |
+| Theme-independent `<head>` / `<body>` injection (analytics, consent) | | ✓ (`publicHead` / `publicBodyEnd`) |
+| Per-post machine-readable metadata (JSON-LD, etc.) | | ✓ (`schema` via `publicBodyForPost`) |
+| Code you want to share across multiple ampless sites | | ✓ (publish as npm package) |
+Rule of thumb:
+- Theme = **what the page looks like**. Read-only at render time.
+- Plugin = **what happens beyond rendering**: admin-editable config,
+  background processing, theme-agnostic injection, machine-readable
+  metadata, cross-site reusability.
+The two boundaries that frequently catch new authors:
+- **Storage / DynamoDB / external API writes belong in a plugin**, never
+  a theme. Themes only read.
+- **A feature you want admins to toggle from `/admin/plugins` belongs
+  in a plugin**, even if its visible effect is purely cosmetic. Themes
+  carry their own settings, but those are theme-display settings, not
+  site-operational ones.
+Some features genuinely sit at the boundary — see [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md)
+for the longer discussion.
+---
 ## 1. What a plugin can do
+ampless plugins are written in one of three places — pick the one
+that matches how widely you want the code shared:
+| Where | Use when | Lives in |
+|---|---|---|
+| **First-party** | Building on the ampless core for everyone | `packages/plugin-*/` in the ampless monorepo |
+| **Site-local** | Site-specific customisation, no separate publish | `plugins/<name>/` inside your site repo |
+| **External npm package** | Sharing with other sites, ready to `npm publish` | A standalone repo (`@scope/ampless-plugin-foo`) |
+All three forms call the same `definePlugin({...})` factory and use the
+same surfaces. The differences are packaging, distribution, and the
+opt-in install-time validation that the static `package.json#amplessPlugin`
+manifest enables (see §3 below).
+§14 below has a one-command scaffold (`npx create-ampless plugin <name>`)
+that produces ready-to-use boilerplate for either of the latter two.
 An ampless plugin is a TypeScript module that returns an
 `AmplessPlugin` object. It plugs into one or more of the following
 surfaces:
@@ -38,36 +92,72 @@ surfaces:
 | `hooks` | trust_level-matched processor Lambda | async, on SQS event | Existing |
 | `settings.public` | `/admin/plugins` form | declarative manifest | 2 |
-What a plugin **cannot** do today (without privileged tier work, see
-roadmap):
-- Inject arbitrary `ReactNode` into pages — descriptor variants only.
-- Open a TCP socket in the public Next.js process. Trusted Lambdas
-  have outbound HTTP only.
-- Add admin routes / server routes / content fields — those
-  capabilities are reserved for Phase 6b.
-- Read or write secrets. The `secretSettings` capability is reserved
-  for Phase 6a.
+A few surfaces don't exist yet — they're reserved for later phases
+and aren't shaped by `definePlugin` today:
+- **Arbitrary `ReactNode` injection into pages.** The sync render
+  surfaces (`publicHead`, `publicBodyEnd`, `publicBodyForPost`) only
+  return descriptor variants. The descriptor validator is the safety
+  boundary for what the runtime renders into the page; it isn't a JS
+  sandbox around the plugin itself. (Plugins run as ordinary
+  TypeScript in the same Node process as the rest of the site.)
+- **Network inside the sync render surfaces.** The sync surfaces are
+  shaped for declarative output — they don't take a Promise and there's
+  no async result path, so doing `await fetch(...)` inside `publicHead`
+  blocks SSR with no way to surface a deadline. Trusted Lambdas
+  (`hooks`) are where the runtime expects outbound HTTP. Background
+  work belongs there.
+- **Admin routes / server routes / content fields.** Reserved for
+  Phase 6b.
+- **Secrets.** The `secretSettings` capability is reserved for
+  Phase 6a; nothing in `settings.public` should be a credential.
 ---
 ## 2. Minimum file layout
-A plugin can ship as a tiny npm package or live in your site's
-monorepo. The on-disk shape is the same either way:
+The fastest way to create a plugin is to scaffold one:
+```bash
+# Site-local (writes plugins/<name>/index.ts in the current ampless site)
+npx create-ampless@latest plugin my-thing
+# Standalone npm package (writes ./<name>/ ready for `npm publish`)
+npx create-ampless@latest plugin @myscope/ampless-plugin-my-thing --standalone
+```
+§14 covers the full flow. The rest of this section explains what the
+generated files mean, so you can author one by hand if you prefer.
+### Site-local
+```
+plugins/
+  my-thing/
+    index.ts        # the factory; that's the whole plugin
+```
+The site's `package.json` / `tsconfig.json` already cover compilation —
+nothing else needs to ship. Register it from `cms.config.ts` with a
+relative import.
+### Standalone npm package
 ```
-my-plugin/
+ampless-plugin-my-thing/
   package.json
   tsconfig.json
   tsup.config.ts
+  README.md
+  CHANGELOG.md
   src/
     index.ts
     index.test.ts
 ```
 See `packages/plugin-rss/` and `packages/plugin-analytics-ga4/` in
-this repo for working examples.
+this repo for working first-party examples — the standalone scaffold
+mirrors their layout.
 The bare-minimum `src/index.ts`:
@@ -108,6 +198,7 @@ That's it. Restart `npm run dev`, view source on any page, and the
 ```ts
 interface AmplessPlugin {
   name: string                      // package-like identifier, e.g. 'analytics-ga4'
+  packageName?: string              // npm package name for install-time cross-check
   apiVersion: 1                     // bump only when the contract changes
   trust_level: 'untrusted' | 'trusted' | 'privileged'
   instanceId?: string               // namespace for multi-instance installs
@@ -159,6 +250,87 @@ What `/admin/plugins` shows as the panel heading. A plain string is
 fine for single-locale plugins; the per-locale map form
 (`{ en: 'GA4', ja: 'GA4' }`) reads from the admin's active locale.
+### `packageName`
+Optional. When set, the runtime resolves
+`<packageName>/package.json` at startup and cross-checks the static
+`amplessPlugin` block there against the factory return value. This
+catches install-time mistakes a plugin author would otherwise only see
+at runtime (or never — capability mismatches don't crash, they just
+quietly skip the surface).
+For standalone plugins, set this to the npm package name your
+`package.json#name` declares:
+```ts
+return definePlugin({
+  name: 'site-verification',
+  packageName: '@ishinao/ampless-plugin-site-verification',
+  apiVersion: 1,
+  // ...
+})
+```
+Site-local plugins don't need it — leave it unset and the cross-check
+is skipped (backward compatible, identical to plugins predating Phase
+5).
+### Static manifest in `package.json` (standalone plugins only)
+For the cross-check to find the static manifest, two things must be
+true about your published package:
+1. `package.json#amplessPlugin` declares the same fields the factory
+   returns:
+   ```json
+   "amplessPlugin": {
+     "apiVersion": 1,
+     "name": "site-verification",
+     "trustLevel": "untrusted",
+     "capabilities": ["publicHead", "adminSettings"],
+     "displayName": { "en": "Site verification", "ja": "サイト所有権確認" }
+   }
+   ```
+2. `package.json#exports` explicitly exposes `./package.json`:
+   ```json
+   "exports": {
+     ".": {
+       "import": "./dist/index.js",
+       "types": "./dist/index.d.ts"
+     },
+     "./package.json": "./package.json"
+   }
+   ```
+   Without this, Node's package-exports gating rejects
+   `import.meta.resolve('<pkg>/package.json')` with
+   `ERR_PACKAGE_PATH_NOT_EXPORTED` and the runtime silently skips the
+   cross-check (your plugin still runs; you just don't get the
+   install-time guard).
+The `create-ampless plugin --standalone` scaffold ships both correctly.
+Add a `"ampless-plugin"` entry to your `package.json#keywords` while
+you're there — it's the convention used by npm searches surfacing
+ampless plugins.
+What the runtime checks:
+| Field | Mismatch behaviour |
+|---|---|
+| `apiVersion` (factory vs manifest) | **Throws** at startup |
+| `apiVersion` (newer than runtime supports) | **Throws** at startup |
+| `name` | Warns in dev |
+| `trustLevel` | Warns in dev |
+| `capabilities` (set comparison) | Warns in dev |
+The two `apiVersion` cases are the only failure that aborts startup —
+they protect against loading a plugin built for an ampless API the
+runtime can't speak. Everything else is a developer-visible warning,
+not a runtime block.
 ---
 ## 4. Picking a `trust_level`
@@ -194,8 +366,12 @@ redeploying.
 ## 5. Sync surfaces
 These run inside the **public Next.js process** (the site visitor's
-request thread). They are pure with respect to AWS — no IAM, no
-network — and execute synchronously.
+request thread) and execute synchronously. They aren't designed to
+do network I/O: there's no async result path, so an `await fetch(...)`
+inside `publicHead` would block SSR with no deadline. Side effects
+that need network calls go in `hooks` (trusted Lambdas, async).
+Public-process plugin code runs with the public-page IAM role — no
+elevated AWS access.
 | Surface | Returns | Use case |
 |---|---|---|
@@ -222,9 +398,14 @@ The `ctx` object carries:
 ## 6. Descriptor reference
 `publicHead` and `publicBodyEnd` return **descriptor objects**, not
-`ReactNode`. The runtime validates them, then builds the React
-elements itself. This is the safety boundary that lets ampless run
-untrusted code in the public render path.
+`ReactNode`. The runtime validates them (URL scheme denylist, attrs
+allowlist, dedup by id) and then builds the React elements itself.
+This is the safety boundary for the **HTML output** a plugin can
+contribute — it bounds what the runtime emits, not what the plugin's
+own code does. Plugins run as ordinary TypeScript in the same Node
+process as the rest of the site; the descriptor pipeline keeps the
+public-page surface narrow and auditable without depending on a JS
+sandbox.
 ### Common variants
@@ -393,6 +574,49 @@ and renders the returned descriptors. The runtime inserts a
 `<script type="application/ld+json">` element with the auto-escaped
 body into the page.
+### Client-side DOM mutation: don't
+Inline scripts you return from `publicHead` or `publicBodyEnd` execute
+during HTML parsing, before React hydrates the page. **They must not
+mutate visible DOM inside a React-managed subtree** — when hydration
+runs, React sees a tree that doesn't match its virtual DOM, throws a
+`Hydration failed because the server rendered HTML didn't match the
+client` error, and regenerates the subtree from scratch. Your inserted
+nodes get wiped.
+React 19 additionally refuses to execute `<script>` tags it
+encounters while rendering a client component, so a script that did
+something like `document.body.append(myNewElement)` may not even fire.
+**Safe patterns**:
+- **Global state / non-DOM side effects**: push to `window.dataLayer`,
+  set a config object, instantiate an analytics SDK. This is what
+  `@ampless/plugin-analytics-ga4`, `@ampless/plugin-gtm`, and
+  `@ampless/plugin-plausible` do.
+- **External widget loaders**: load a third-party script that manages
+  its own isolated container (Crisp, Intercom, Drift). The widget's
+  shadow DOM / fixed-position overlay lives outside React's tree and
+  doesn't conflict with hydration.
+- **SSR-only descriptors**: return `meta` / `link` / `noscript` (and,
+  on `publicBodyEnd`, `iframe`) — the runtime renders these
+  server-side and they're part of React's virtual DOM from the start.
+**Patterns to avoid**:
+- `document.createElement('div')` + `document.body.append(...)`
+- Modifying classes / attributes / text content of elements rendered
+  by the theme
+- Inserting per-post HTML by reading something like `#post-body`
+  client-side — there's no `publicHead`-for-post analogue today, and
+  any client-side rewrite of a server-rendered subtree races against
+  hydration
+For visible per-post output, return JSON-LD via `publicBodyForPost`
+(see §6's `PublicPostBodyDescriptor`) or stick with the theme's own
+templates. A future ampless capability for server-side per-post HTML
+injection is on the roadmap.
 ---
 ## 7. Async event hooks
@@ -757,7 +981,100 @@ Worked examples to crib from:
 ---
-## 14. Where to ask
+## 14. Quickstart: scaffolding with `create-ampless`
+For a fast path from idea to working plugin, the `create-ampless`
+CLI ships a `plugin <name>` subcommand:
+```bash
+# Site-local: scaffolds plugins/<name>/index.ts inside the current
+# ampless site. Run from the site repo root.
+npx create-ampless@latest plugin my-thing \
+  --trust-level untrusted \
+  --capabilities publicHead,adminSettings
+# Standalone npm package: scaffolds ./<dir>/ with package.json,
+# tsconfig.json, tsup.config.ts, README + .ja, CHANGELOG, .gitignore,
+# and src/index.ts + src/index.test.ts. Run from wherever you want
+# the new package directory to land.
+npx create-ampless@latest plugin @myscope/ampless-plugin-thing \
+  --standalone \
+  --trust-level untrusted \
+  --capabilities publicHead,adminSettings \
+  --description "What this plugin does"
+```
+Standalone scaffolds include everything Phase 5's cross-check needs:
+`package.json#amplessPlugin`, the `./package.json` subpath export,
+the `packageName` factory field, the `ampless-plugin` discovery
+keyword, and a minimal vitest sample so `pnpm install && pnpm test &&
+pnpm build` runs clean on the freshly generated directory.
+Both modes also accept a positional flag-less invocation (`npx
+create-ampless@latest plugin`) that walks you through the same
+questions interactively via the @clack prompt UI.
+### Publishing a standalone plugin
+```bash
+cd ampless-plugin-thing
+pnpm install
+pnpm test
+pnpm build
+pnpm publish --access public --tag alpha
+```
+`--access public` is mandatory for scoped names (`@scope/...`).
+`--tag alpha` matches the current ampless pre-release cadence — drop
+it once the package reaches a stable major.
+There's a publish-to-install lag of "seconds to minutes" before
+`npm install <pkg>@alpha` picks up a fresh publish (CDN + registry
+replica propagation). If `npm install` 404s right after `npm publish`
+returns, wait 1-2 minutes and retry — `npm view <pkg>@alpha version`
+visible in the registry is necessary but sometimes not sufficient.
+### Naming the package
+By npm convention, scope and the conventional `ampless-plugin-`
+prefix collapse to a short identifier for `AmplessPlugin.name`:
+| npm package | `AmplessPlugin.name` |
+|---|---|
+| `@ampless/plugin-gtm` | `gtm` |
+| `@scope/ampless-plugin-clarity` | `clarity` |
+| `ampless-plugin-readme-toc` | `readme-toc` |
+| `weird-name-no-prefix` | `weird-name-no-prefix` |
+The scaffold does this stripping automatically. Hand-author the same
+mapping if you skip the scaffold; the install-time cross-check warns
+on a mismatch between the package's static manifest and the factory.
+### Site-local follow-up
+After a site-local scaffold:
+```ts
+// cms.config.ts
+import myThingPlugin from './plugins/my-thing'
+export default defineConfig({
+  // ...
+  plugins: [
+    myThingPlugin(),
+  ],
+})
+```
+The scaffold prints this snippet at the end of its run — copy it into
+`cms.config.ts` to activate the plugin.
+`update-ampless` never touches the `plugins/` directory (it's
+PROTECTED), so the scaffolded code is safe across ampless upgrades.
+---
+## 15. Where to ask
 - Architecture / design questions → [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md)
 - Bugs in a first-party plugin → file an issue against

package/dist/templates/_shared/package.json CHANGED Viewed

@@ -25,19 +25,19 @@
     "@tiptap/pm": "^3.23.6",
     "@tiptap/react": "^3.23.6",
     "@tiptap/starter-kit": "^3.23.6",
-    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.5",
-    "@ampless/plugin-gtm": "^0.1.1-alpha.4",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.22",
-    "@ampless/plugin-plausible": "^0.1.1-alpha.4",
-    "@ampless/plugin-rss": "^0.2.0-alpha.22",
-    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.1",
-    "@ampless/plugin-seo": "^0.2.0-alpha.22",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.22",
-    "@ampless/admin": "^1.0.0-alpha.49",
-    "@ampless/backend": "^1.0.0-alpha.39",
-    "@ampless/runtime": "^1.0.0-alpha.28",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.6",
+    "@ampless/plugin-gtm": "^0.1.1-alpha.5",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.23",
+    "@ampless/plugin-plausible": "^0.1.1-alpha.5",
+    "@ampless/plugin-rss": "^0.2.0-alpha.23",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.2",
+    "@ampless/plugin-seo": "^0.2.0-alpha.23",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.23",
+    "@ampless/admin": "^1.0.0-alpha.50",
+    "@ampless/backend": "^1.0.0-alpha.40",
+    "@ampless/runtime": "^1.0.0-alpha.29",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.22",
+    "ampless": "^1.0.0-alpha.23",
     "aws-amplify": "^6.17.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/dist/templates/_shared/plugins/README.ja.md CHANGED Viewed

@@ -10,14 +10,38 @@
 ## いつ使うか
-サイト固有の機能で、以下に当てはまるときに使う:
-- プラグイン surface (`publicHead` / `publicBodyEnd` / `metadata` / `eventHooks` 等) が必要
-- このサイト限定の用途 (一度きりのフッタークレジット、サイト特有の JSON-LD 拡張、まだ汎用化したくない analytics スニペット等)
+詳しい判断軸は [プラグイン作者ガイド](../docs/plugin-author-guide.ja.md)
+§0「テーマとプラグインの境界線」に書いてある。プラグインが初めて、または
+「これはテーマ側に書くべきか、プラグインか」で迷ったら先にそちらを読む。
+ざっくり言うと:
+- **テーマ** = ページの見た目 (レイアウト / コンポーネント / CSS)
+- **プラグイン** = admin で編集する設定、バックグラウンド処理、
+  テーマを横断する注入、機械可読メタデータ、複数サイトで共有したい機能
+その中でも *ローカル* プラグイン (このディレクトリ) を使うのは、サイト
+固有の機能で:
+- プラグイン surface (`publicHead` / `publicBodyEnd` / `metadata` /
+  `eventHooks` 等) が必要
+- このサイト限定の用途 (一度きりのフッタークレジット、サイト特有の
+  JSON-LD 拡張、まだ汎用化したくない analytics スニペット等)
 - 別パッケージとして version 上げて publish するのは大袈裟
-複数サイトで使いたくなったら、独立 npm パッケージに切り出す (Phase 5 で
-`npx create-ampless plugin --standalone` が来る予定。今は手でコピーで OK)。
+複数サイトで使いたくなったら、独立 npm パッケージに切り出す:
+`npx create-ampless@latest plugin <name> --standalone` で publish 用の
+ディレクトリ一式が scaffold される。
+## クライアントサイドスクリプトに関する注意
+`publicHead` / `publicBodyEnd` で `inlineScript` を返す場合、その body の
+中で **可視 DOM 要素を挿入してはいけない**。React の hydration は DOM が
+virtual DOM と一致していることを前提にしていて、外部からの DOM 操作は
+reconciliation で消されてコンソールに hydration error が出る。
+安全なパターンは `window.dataLayer` 等のグローバル状態操作、自分で隔離
+コンテナを持つ外部ウィジェットローダ、そして SSR 専用 descriptor (`meta` /
+`link` / `noscript` / `iframe`)。詳細は [作者ガイド §6](../docs/plugin-author-guide.ja.md)
+「クライアント側 DOM 変更は禁止」セクションを参照。
 ## 最小例

package/dist/templates/_shared/plugins/README.md CHANGED Viewed

@@ -10,15 +10,41 @@ add here is yours to keep.
 ## When to use a local plugin
-Reach for a local plugin when you want a site-specific feature that:
-- needs the plugin surface (`publicHead` / `publicBodyEnd` / `metadata` / `eventHooks` / etc.)
-- is specific to this site (a one-off footer credit, a custom JSON-LD enrichment, an analytics snippet you're not yet ready to ship as a reusable package)
+The longer answer lives in §0 ("Theme vs Plugin Boundary") of the
+[plugin author guide](../docs/plugin-author-guide.md) — read that
+first if you're new to plugins, or if you're unsure whether a feature
+belongs in a plugin or a theme. Short version:
+- **Theme** = what the page looks like (layout, components, CSS).
+- **Plugin** = admin-editable config, background processing,
+  theme-agnostic injection, machine-readable metadata, or anything
+  you want to share between sites.
+Reach for a *local* plugin (this directory) when you want a feature
+that:
+- needs a plugin surface (`publicHead` / `publicBodyEnd` /
+  `metadata` / `eventHooks` / etc.)
+- is specific to this site (a one-off footer credit, a custom JSON-LD
+  enrichment, an analytics snippet you're not yet ready to ship as a
+  reusable package)
 - you'd rather not version-bump or republish to iterate on
 When the plugin grows useful for more than one site, lift it into its
-own npm package (see `npx create-ampless plugin --standalone` once it
-ships in Phase 5; for now you can copy it out by hand).
+own npm package — `npx create-ampless@latest plugin <name> --standalone`
+scaffolds the directory ready for `npm publish`.
+## A note on client-side scripts
+If your `publicHead` / `publicBodyEnd` returns an `inlineScript`, the
+script body **must not insert visible DOM elements** into the page.
+React's hydration assumes the DOM matches its virtual DOM, and any
+foreign nodes get wiped during reconciliation (plus a console error).
+Safe patterns are `window.dataLayer`-style global state, external
+widget loaders that manage their own isolated container, and
+SSR-only descriptors (`meta` / `link` / `noscript` / `iframe`).
+See the [author guide §6](../docs/plugin-author-guide.md) "Client-side
+DOM mutation: don't" section for the full story.
 ## Minimal example

package/dist/templates/plugin-local/README.md ADDED Viewed

@@ -0,0 +1,34 @@
+# {{nameKebab}}
+{{description}}
+Site-local plugin in `plugins/{{nameKebab}}/`. This directory is
+user-owned: `update-ampless` never touches it.
+## Register
+Add to `cms.config.ts`:
+```typescript
+import {{nameCamelCase}}Plugin from './plugins/{{nameKebab}}'
+export default defineConfig({
+  // ...
+  plugins: [
+    {{nameCamelCase}}Plugin(),
+  ],
+})
+```
+Restart `next dev` and visit `/admin/plugins` to configure.
+## Settings
+(none yet — declare via `settings.public` in `index.ts`)
+## Notes
+- Trust level: `{{trustLevel}}`
+- Capabilities: `{{capabilitiesList}}`
+- When this plugin grows useful for more than one site, lift it into
+  its own npm package via `npx create-ampless plugin <name> --standalone`.

package/dist/templates/plugin-local/index.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { definePlugin, type AmplessPlugin } from 'ampless'
+export interface {{NameCamelCase}}Options {
+  /** Optional namespace when registering multiple instances. */
+  instanceId?: string
+  // TODO: add the constructor options your plugin needs.
+}
+/**
+ * {{description}}
+ *
+ * Site-local plugin. Add to your `cms.config.ts`:
+ *
+ *     import {{nameCamelCase}}Plugin from './plugins/{{nameKebab}}'
+ *
+ *     export default defineConfig({
+ *       // ...
+ *       plugins: [
+ *         {{nameCamelCase}}Plugin(),
+ *       ],
+ *     })
+ */
+export default function {{nameCamelCase}}Plugin(
+  options: {{NameCamelCase}}Options = {}
+): AmplessPlugin {
+  const instanceId = options.instanceId ?? '{{nameKebab}}'
+  return definePlugin({
+    name: '{{nameKebab}}',
+    instanceId,
+    apiVersion: 1,
+    trust_level: '{{trustLevel}}',
+    displayName: { en: '{{DisplayName}}', ja: '{{displayNameJa}}' },
+    capabilities: [{{capabilitiesList}}],
+    // TODO: implement the surfaces declared in `capabilities`. The
+    // most common starting point is `publicHead(ctx)` returning a
+    // descriptor array. See the plugin author guide:
+    //   https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md
+  })
+}

package/dist/templates/plugin-standalone/CHANGELOG.md ADDED Viewed

	@@ -0,0 +1 @@
1	+ # {{packageName}}

package/dist/templates/plugin-standalone/README.ja.md ADDED Viewed

@@ -0,0 +1,43 @@
+> English: [README.md](./README.md)
+# {{packageName}}
+> [Pre-release / alpha] {{description}}
+## インストール
+```bash
+npm install {{packageName}}@alpha
+```
+## 設定
+```typescript
+// cms.config.ts
+import { defineConfig } from 'ampless'
+import {{nameCamelCase}}Plugin from '{{packageName}}'
+export default defineConfig({
+  // ...
+  plugins: [
+    {{nameCamelCase}}Plugin(),
+  ],
+})
+```
+`/admin/plugins` で設定。
+## Trust level
+`{{trustLevel}}`。Capabilities: `{{capabilitiesList}}`。
+## Publish
+```bash
+pnpm install
+pnpm test
+pnpm build
+pnpm publish --access public --tag alpha
+```
+API 詳細は [ampless plugin author guide](https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md) を参照。