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

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { spinner as spinner2, outro as outro3, log as log5 } from "@clack/prompts";
-import { existsSync as existsSync7 } from "fs";
-import { basename as basename3, resolve as resolve5 } from "path";
+import { spinner as spinner2, outro as outro4, log as log6 } from "@clack/prompts";
+import { existsSync as existsSync8 } from "fs";
+import { basename as basename4, resolve as resolve5 } from "path";
 
 // src/prompts.ts
 import * as p from "@clack/prompts";
@@ -106,6 +106,9 @@ function sharedTemplateDir() {
 function templatePath(theme) {
   return resolve(templatesDir, theme);
 }
+function pluginTemplateDir(mode) {
+  return resolve(templatesDir, mode === "local" ? "plugin-local" : "plugin-standalone");
+}
 
 // src/gitignore.ts
 var DEFAULT_GITIGNORE = `# Dependencies
@@ -269,6 +272,20 @@ async function scaffold(sharedDir, themesRoot, destDir, opts) {
 // src/args.ts
 var VALID_THEMES = ["blog", "minimal", "landing", "corporate", "docs", "dads"];
 var VALID_PLUGINS = ["seo", "rss", "webhook"];
+var VALID_PLUGIN_TRUST_LEVELS = [
+  "untrusted",
+  "trusted",
+  "privileged"
+];
+var VALID_PLUGIN_CAPABILITIES = [
+  "publicHead",
+  "publicBody",
+  "metadata",
+  "eventHooks",
+  "adminSettings",
+  "writePublicAsset",
+  "schema"
+];
 var STRING_FLAGS = /* @__PURE__ */ new Set([
   "--site-name",
   "--themes",
@@ -279,7 +296,11 @@ var STRING_FLAGS = /* @__PURE__ */ new Set([
   "--aws-region",
   "--domain",
   "--subdomain",
-  "--iam-service-role"
+  "--iam-service-role",
+  // Phase 5 `plugin <name>` flags
+  "--trust-level",
+  "--capabilities",
+  "--description"
 ]);
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--deploy",
@@ -291,7 +312,10 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--create-iam-role",
   "--skip-confirm",
   "--help",
-  "-h"
+  "-h",
+  // Phase 5 `plugin <name>` mode flags
+  "--local",
+  "--standalone"
 ]);
 function parseDeployArgs(argv) {
   const out = {
@@ -299,6 +323,7 @@ function parseDeployArgs(argv) {
     mount: false,
     upgrade: false,
     copyTheme: false,
+    createPlugin: false,
     dryRun: false,
     noInstall: false,
     githubPrivate: false,
@@ -346,6 +371,18 @@ function parseDeployArgs(argv) {
         case "-h":
           out.help = true;
           break;
+        case "--local":
+          if (out.pluginMode === "standalone") {
+            throw new Error("Cannot combine --local and --standalone");
+          }
+          out.pluginMode = "local";
+          break;
+        case "--standalone":
+          if (out.pluginMode === "local") {
+            throw new Error("Cannot combine --local and --standalone");
+          }
+          out.pluginMode = "standalone";
+          break;
       }
       continue;
     }
@@ -401,6 +438,31 @@ function parseDeployArgs(argv) {
         case "--iam-service-role":
           out.iamServiceRole = value;
           break;
+        case "--trust-level": {
+          if (!VALID_PLUGIN_TRUST_LEVELS.includes(value)) {
+            throw new Error(
+              `Invalid --trust-level "${value}". Valid values: ${VALID_PLUGIN_TRUST_LEVELS.join(", ")}`
+            );
+          }
+          out.pluginTrustLevel = value;
+          break;
+        }
+        case "--capabilities": {
+          const caps = value.split(",").map((c) => c.trim()).filter(Boolean);
+          const invalid = caps.filter(
+            (c) => !VALID_PLUGIN_CAPABILITIES.includes(c)
+          );
+          if (invalid.length > 0) {
+            throw new Error(
+              `Invalid capability(ies): ${invalid.join(", ")}. Valid values: ${VALID_PLUGIN_CAPABILITIES.join(", ")}`
+            );
+          }
+          out.pluginCapabilities = caps;
+          break;
+        }
+        case "--description":
+          out.pluginDescription = value;
+          break;
       }
       continue;
     }
@@ -424,6 +486,14 @@ function parseDeployArgs(argv) {
       out.copyThemeTarget = raw;
       continue;
     }
+    if (raw === "plugin" && out.projectName === void 0 && !out.createPlugin && !out.upgrade && !out.copyTheme) {
+      out.createPlugin = true;
+      continue;
+    }
+    if (out.createPlugin && out.pluginName === void 0) {
+      out.pluginName = raw;
+      continue;
+    }
     if (out.projectName === void 0) {
       out.projectName = raw;
     } else {
@@ -436,8 +506,10 @@ var HELP_TEXT = `create-ampless \u2014 scaffold an ampless project
 
 Usage:
   npx create-ampless@latest <project-name> [options]
-  npx create-ampless@latest --mount [options]    # in an existing project dir
-  npx create-ampless@latest upgrade [options]    # in an existing project dir
+  npx create-ampless@latest --mount [options]               # in an existing project dir
+  npx create-ampless@latest upgrade [options]               # in an existing project dir
+  npx create-ampless@latest copy-theme <src> <dst>          # in an existing project dir
+  npx create-ampless@latest plugin <name> [options]         # scaffold a plugin (Phase 5)
 
 Options:
   --site-name <name>          Site display name (default: "My Blog")
@@ -488,6 +560,32 @@ copy-theme <source> <target>
          it alone). Run inside an existing ampless project.
 
          Example: npx create-ampless@latest copy-theme blog my-blog
+
+plugin <name>
+         Scaffold an ampless plugin. Two modes:
+
+  --local                     Default. Writes plugins/<name>/index.ts inside
+                              the current ampless site. The site itself is the
+                              build / publish unit; the plugin file is just
+                              code that sits there. Plugin name is a kebab-case
+                              identifier (e.g. "site-verification").
+
+  --standalone                Writes a complete npm package at ./<name>/ ready
+                              for 'npm publish'. Plugin name should be the npm
+                              package name (e.g. "@scope/ampless-plugin-foo"
+                              or "ampless-plugin-foo"); the kebab segment
+                              becomes the AmplessPlugin.name.
+
+  --trust-level <value>       'untrusted' (default), 'trusted', or 'privileged'
+  --capabilities <list>       Comma-separated. Valid: publicHead, publicBody,
+                              metadata, eventHooks, adminSettings,
+                              writePublicAsset, schema
+                              (default: publicHead,adminSettings)
+  --description "<text>"      Optional one-line description
+
+         Examples:
+           npx create-ampless@latest plugin site-verification
+           npx create-ampless@latest plugin @ishinao/ampless-plugin-foo --standalone
 `;
 
 // src/deploy-prompts.ts
@@ -2210,12 +2308,289 @@ async function runCopyTheme(args) {
   }
 }
 
-// src/index.ts
+// src/plugin.ts
+import { cp as cp4, mkdir as mkdir3, readFile as readFile5, writeFile as writeFile5, readdir as readdir5 } from "fs/promises";
+import { existsSync as existsSync7 } from "fs";
+import { join as join5, extname as extname3, basename as basename3 } from "path";
+import {
+  log as log5,
+  outro as outro3,
+  text as text3,
+  select as select2,
+  multiselect as multiselect2,
+  isCancel as isCancel3,
+  cancel as cancel3
+} from "@clack/prompts";
 import pc5 from "picocolors";
+var SCAFFOLD_AMPLESS_VERSION = "1.0.0-alpha.22";
+var TEXT_EXTENSIONS3 = /* @__PURE__ */ new Set([
+  ".json",
+  ".md",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".html",
+  ".css",
+  ".env",
+  ".txt",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".gitignore"
+]);
+function toKebab(s) {
+  return s.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase()).replace(/^-/, "");
+}
+function toCamelCase(kebab) {
+  return kebab.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function toPascalCase(kebab) {
+  const c = toCamelCase(kebab);
+  return c.charAt(0).toUpperCase() + c.slice(1);
+}
+function toDisplayName(kebab) {
+  const words = kebab.split("-");
+  return words.map((w, i) => i === 0 ? w.charAt(0).toUpperCase() + w.slice(1) : w).join(" ");
+}
+function sanitizeForJsComment(s) {
+  return s.replace(/\*\//g, "*\\/").replace(/[\r\n]+/g, " ").replace(/\s{2,}/g, " ").trim();
+}
+function lastSegment(packageName) {
+  return packageName.replace(/^@[^/]+\//, "");
+}
+function pluginNameFromPackage(packageName) {
+  const segment = lastSegment(packageName);
+  if (segment.startsWith("ampless-plugin-")) {
+    return segment.slice("ampless-plugin-".length);
+  }
+  if (segment.startsWith("plugin-")) {
+    return segment.slice("plugin-".length);
+  }
+  return segment;
+}
+async function substituteFile2(filePath, vars) {
+  const ext = extname3(filePath) || (basename3(filePath) === ".gitignore" ? ".gitignore" : "");
+  if (!TEXT_EXTENSIONS3.has(ext)) return;
+  const content = await readFile5(filePath, "utf-8");
+  const replaced = content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
+  if (replaced !== content) await writeFile5(filePath, replaced, "utf-8");
+}
+async function substituteDir2(dir, vars) {
+  const entries = await readdir5(dir, { withFileTypes: true });
+  await Promise.all(
+    entries.map(async (entry) => {
+      const fullPath = join5(dir, entry.name);
+      if (entry.isDirectory()) {
+        await substituteDir2(fullPath, vars);
+      } else {
+        await substituteFile2(fullPath, vars);
+      }
+    })
+  );
+}
+var KEBAB_RE = /^[a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)*$/;
+var PACKAGE_NAME_RE = /^(@[a-z][a-z0-9-]*\/)?[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+async function runCreatePluginIn(destDir, args) {
+  const mode = args.pluginMode ?? "local";
+  let rawName = args.pluginName;
+  if (!rawName) {
+    if (args.skipConfirm === true) {
+      throw new Error(
+        mode === "local" ? "Plugin name is required when --skip-confirm is set. Pass it as the positional argument: `create-ampless plugin <name> --skip-confirm`." : "Plugin package name is required when --skip-confirm is set. Pass it as the positional argument: `create-ampless plugin <package-name> --standalone --skip-confirm`."
+      );
+    }
+    const answer = await text3({
+      message: mode === "local" ? 'Plugin name (kebab-case, e.g. "site-verification"):' : 'Plugin package name (e.g. "@scope/ampless-plugin-foo" or "ampless-plugin-foo"):',
+      validate(v) {
+        if (!v) return "Plugin name is required";
+        const re = mode === "local" ? KEBAB_RE : PACKAGE_NAME_RE;
+        if (!re.test(v)) {
+          return mode === "local" ? 'Must be kebab-case starting with a lowercase letter (e.g. "site-verification")' : 'Must be a valid npm package name (e.g. "ampless-plugin-foo" or "@scope/ampless-plugin-foo")';
+        }
+      }
+    });
+    if (isCancel3(answer)) {
+      cancel3("Cancelled.");
+      process.exit(0);
+    }
+    rawName = answer;
+  } else {
+    const re = mode === "local" ? KEBAB_RE : PACKAGE_NAME_RE;
+    if (!re.test(rawName)) {
+      throw new Error(
+        mode === "local" ? `Invalid plugin name "${rawName}". Must be kebab-case (e.g. "site-verification").` : `Invalid plugin name "${rawName}". Must be a valid npm package name (e.g. "ampless-plugin-foo" or "@scope/ampless-plugin-foo").`
+      );
+    }
+  }
+  const skipConfirm = args.skipConfirm === true;
+  let trustLevel = args.pluginTrustLevel;
+  if (!trustLevel) {
+    if (skipConfirm) {
+      trustLevel = "untrusted";
+    } else {
+      const answer = await select2({
+        message: "Trust level:",
+        options: VALID_PLUGIN_TRUST_LEVELS.map((t) => ({
+          value: t,
+          label: t,
+          hint: t === "untrusted" ? "No special permissions (default)" : t === "trusted" ? "Can read site config" : "Full access to internal APIs"
+        }))
+      });
+      if (isCancel3(answer)) {
+        cancel3("Cancelled.");
+        process.exit(0);
+      }
+      trustLevel = answer;
+    }
+  }
+  let capabilities = args.pluginCapabilities;
+  if (!capabilities) {
+    if (skipConfirm) {
+      capabilities = ["publicHead", "adminSettings"];
+    } else {
+      const answer = await multiselect2({
+        message: "Capabilities (space to toggle, enter to confirm):",
+        options: VALID_PLUGIN_CAPABILITIES.map((c) => ({
+          value: c,
+          label: c
+        })),
+        initialValues: ["publicHead", "adminSettings"],
+        required: false
+      });
+      if (isCancel3(answer)) {
+        cancel3("Cancelled.");
+        process.exit(0);
+      }
+      capabilities = answer;
+    }
+  }
+  const rawDescription = args.pluginDescription ?? "";
+  const description = sanitizeForJsComment(rawDescription);
+  const descriptionJson = JSON.stringify(rawDescription);
+  const nameKebab = mode === "local" ? rawName : pluginNameFromPackage(rawName);
+  const packageName = mode === "standalone" ? rawName : nameKebab;
+  if (!KEBAB_RE.test(nameKebab)) {
+    throw new Error(
+      `Invalid plugin name: "${nameKebab}" (derived from "${rawName}" by stripping the npm scope and the conventional ampless-plugin- prefix) is not valid kebab-case. Each segment must start with a letter and contain only letters and digits. Examples: "site-verification", "image-zoom".`
+    );
+  }
+  const nameCamelCase = toCamelCase(nameKebab);
+  const NamePascalCase = toPascalCase(nameKebab);
+  const DisplayName = toDisplayName(nameKebab);
+  void toKebab;
+  let outputDir;
+  if (mode === "local") {
+    const problem = validateMountableProject(destDir);
+    if (problem) {
+      throw new Error(problem);
+    }
+    outputDir = join5(destDir, "plugins", nameKebab);
+    if (existsSync7(outputDir)) {
+      throw new Error(
+        `Plugin directory already exists: plugins/${nameKebab}/
+Remove it first or choose a different name.`
+      );
+    }
+  } else {
+    const nameSegment = lastSegment(rawName);
+    outputDir = join5(destDir, nameSegment);
+    if (existsSync7(outputDir)) {
+      throw new Error(
+        `Directory already exists: ${nameSegment}/
+Remove it first or choose a different name.`
+      );
+    }
+  }
+  const templateDir = pluginTemplateDir(mode);
+  if (!existsSync7(templateDir)) {
+    throw new Error(
+      `Plugin template not found: ${templateDir}
+The ${mode === "local" ? "plugin-local" : "plugin-standalone"} template directory has not been added to the repo yet. Run \`git pull\` to pick up the latest templates.`
+    );
+  }
+  await mkdir3(outputDir, { recursive: true });
+  await cp4(templateDir, outputDir, { recursive: true });
+  const capabilitiesList = capabilities && capabilities.length > 0 ? capabilities.map((c) => `'${c}'`).join(", ") : "";
+  const capabilitiesJsonArray = capabilities && capabilities.length > 0 ? capabilities.map((c) => `"${c}"`).join(", ") : "";
+  const vars = {
+    // Use camelCase keys so they survive substituteVars' `\w+` regex.
+    // Templates reference them as `{{nameKebab}}` (not `{{name-kebab}}`).
+    nameKebab,
+    nameCamelCase,
+    NameCamelCase: NamePascalCase,
+    packageName,
+    description,
+    descriptionJson,
+    trustLevel: trustLevel ?? "untrusted",
+    capabilitiesList,
+    capabilitiesJsonArray,
+    DisplayName,
+    displayNameJa: DisplayName,
+    // same as English for now; maintainers can localise
+    amplessVersion: SCAFFOLD_AMPLESS_VERSION
+  };
+  await substituteDir2(outputDir, vars);
+  return {
+    mode,
+    outputDir,
+    pluginName: nameKebab,
+    packageName: mode === "standalone" ? packageName : void 0
+  };
+}
+async function runCreatePlugin(args) {
+  const destDir = process.cwd();
+  try {
+    const result = await runCreatePluginIn(destDir, args);
+    if (result.mode === "local") {
+      const rel = `plugins/${result.pluginName}/`;
+      const factoryName = `${toCamelCase(result.pluginName)}Plugin`;
+      outro3(
+        `${pc5.green("\u2714")} Plugin scaffolded at ${pc5.bold(rel)}
+
+  Register it in ${pc5.cyan("cms.config.ts")}:
+
+    import ${factoryName} from './plugins/${result.pluginName}'
+
+    export default defineConfig({
+      // ...
+      plugins: [
+        ${factoryName}(),
+      ],
+    })
+
+  Then restart the dev server to pick up the new plugin.`
+      );
+    } else {
+      const dirName = result.packageName ? lastSegment(result.packageName) : result.pluginName;
+      outro3(
+        `${pc5.green("\u2714")} Standalone plugin scaffolded at ${pc5.bold(dirName + "/")}
+
+  Next steps:
+    ${pc5.cyan(`cd ${dirName}`)}
+    ${pc5.cyan("pnpm install")}
+    ${pc5.cyan("pnpm test")}
+    ${pc5.cyan("pnpm build")}
+    ${pc5.cyan("pnpm publish --access public --tag alpha")}
+
+  Then add the published package to your ampless site:
+    ${pc5.cyan(`pnpm add ${result.packageName ?? result.pluginName}`)}`
+      );
+    }
+  } catch (err) {
+    log5.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+import pc6 from "picocolors";
 var DEFAULT_THEMES = VALID_THEMES;
 function buildNonInteractiveOpts(args) {
   const projectName = args.projectName ?? (() => {
-    const b = basename3(process.cwd());
+    const b = basename4(process.cwd());
     return b && b !== "/" ? b : "my-ampless-site";
   })();
   const siteName = args.siteName ?? "My Blog";
@@ -2236,17 +2611,17 @@ function warnIgnoredScaffoldFlags(args) {
   if (args.plugins) ignored.push("--plugins");
   if (args.projectName) ignored.push("<project-name> positional");
   if (ignored.length > 0) {
-    log5.warn(`--mount mode ignores: ${ignored.join(", ")}`);
+    log6.warn(`--mount mode ignores: ${ignored.join(", ")}`);
   }
 }
 async function runMount(args) {
   const destDir = process.cwd();
-  const projectName = basename3(destDir);
+  const projectName = basename4(destDir);
   warnIgnoredScaffoldFlags(args);
   const problem = validateMountableProject(destDir);
   if (problem) {
-    log5.error(problem);
-    log5.info(
+    log6.error(problem);
+    log6.info(
       "Run `npx create-ampless@latest <name>` first to scaffold, or `cd` into a scaffolded project before passing --mount."
     );
     process.exit(1);
@@ -2260,23 +2635,23 @@ async function runMount(args) {
     if (err instanceof PreflightError) {
       process.exit(1);
     }
-    log5.error(err instanceof Error ? err.message : String(err));
+    log6.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
 }
 function printDeployResult(result) {
   const lines = [
-    `${pc5.green("\u2714")} Project deployed`,
+    `${pc6.green("\u2714")} Project deployed`,
     ``,
-    `  GitHub:        ${pc5.cyan(result.githubRepoUrl)}`,
-    `  Amplify app:   ${pc5.cyan(result.amplifyAppId)}`,
-    `  Amplify URL:   ${pc5.cyan(result.amplifyAppUrl)}`
+    `  GitHub:        ${pc6.cyan(result.githubRepoUrl)}`,
+    `  Amplify app:   ${pc6.cyan(result.amplifyAppId)}`,
+    `  Amplify URL:   ${pc6.cyan(result.amplifyAppUrl)}`
   ];
   if (result.domainUrl) {
-    lines.push(`  Custom domain: ${pc5.cyan(result.domainUrl)}`);
+    lines.push(`  Custom domain: ${pc6.cyan(result.domainUrl)}`);
   }
   if (result.domainVerification && result.domainVerification.length > 0) {
-    lines.push("", `  ${pc5.bold("Add these DNS records to verify the domain:")}`);
+    lines.push("", `  ${pc6.bold("Add these DNS records to verify the domain:")}`);
     for (const v of result.domainVerification) {
       lines.push(`    ${v.cname}  CNAME  ${v.target}`);
     }
@@ -2284,9 +2659,9 @@ function printDeployResult(result) {
   lines.push(
     "",
     `  First build is now running in Amplify Hosting.`,
-    `  Watch it at ${pc5.cyan(`https://console.aws.amazon.com/amplify/home#/${result.amplifyAppId}`)}`
+    `  Watch it at ${pc6.cyan(`https://console.aws.amazon.com/amplify/home#/${result.amplifyAppId}`)}`
   );
-  outro3(lines.join("\n"));
+  outro4(lines.join("\n"));
 }
 async function main() {
   const args = parseDeployArgs(process.argv.slice(2));
@@ -2295,7 +2670,7 @@ async function main() {
     return;
   }
   for (const flag of args.unknown) {
-    log5.warn(`Unknown argument ignored: ${flag}`);
+    log6.warn(`Unknown argument ignored: ${flag}`);
   }
   if (args.upgrade) {
     await runUpgrade(args);
@@ -2305,6 +2680,10 @@ async function main() {
     await runCopyTheme(args);
     return;
   }
+  if (args.createPlugin) {
+    await runCreatePlugin(args);
+    return;
+  }
   if (args.mount) {
     await runMount(args);
     return;
@@ -2317,8 +2696,8 @@ async function main() {
   }
   if (!opts) return;
   const destDir = resolve5(process.cwd(), opts.projectName);
-  if (existsSync7(destDir)) {
-    log5.error(`Directory already exists: ${destDir}`);
+  if (existsSync8(destDir)) {
+    log6.error(`Directory already exists: ${destDir}`);
     process.exit(1);
   }
   const sharedDir = sharedTemplateDir();
@@ -2329,7 +2708,7 @@ async function main() {
     s.stop("Done!");
   } catch (err) {
     s.stop("Failed.");
-    log5.error(String(err));
+    log6.error(String(err));
     process.exit(1);
   }
   if (args.deploy) {
@@ -2342,18 +2721,18 @@ async function main() {
       if (err instanceof PreflightError) {
         process.exit(1);
       }
-      log5.error(err instanceof Error ? err.message : String(err));
+      log6.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
     return;
   }
-  outro3(
-    `${pc5.green("\u2714")} Project created at ${pc5.bold(opts.projectName)}
+  outro4(
+    `${pc6.green("\u2714")} Project created at ${pc6.bold(opts.projectName)}
 
   Next steps:
-    ${pc5.cyan("cd")} ${opts.projectName}
-    ${pc5.cyan("npm install")}
-    ${pc5.cyan("npm run sandbox")}   ${pc5.dim("# deploy sandbox + start Next.js")}`
+    ${pc6.cyan("cd")} ${opts.projectName}
+    ${pc6.cyan("npm install")}
+    ${pc6.cyan("npm run sandbox")}   ${pc6.dim("# deploy sandbox + start Next.js")}`
   );
 }
 main().catch((err) => {

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

@@ -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

@@ -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

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

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

@@ -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) を参照。

package/dist/templates/plugin-standalone/README.md

@@ -0,0 +1,43 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+
+# {{packageName}}
+
+> [Pre-release / alpha] {{description}}
+
+## Install
+
+```bash
+npm install {{packageName}}@alpha
+```
+
+## Configure
+
+```typescript
+// cms.config.ts
+import { defineConfig } from 'ampless'
+import {{nameCamelCase}}Plugin from '{{packageName}}'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    {{nameCamelCase}}Plugin(),
+  ],
+})
+```
+
+Then go to `/admin/plugins` to configure.
+
+## Trust level
+
+`{{trustLevel}}`. Capabilities: `{{capabilitiesList}}`.
+
+## Publishing
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+pnpm publish --access public --tag alpha
+```
+
+See the [ampless plugin author guide](https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md) for the full API.

package/dist/templates/plugin-standalone/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": {{descriptionJson}},
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "ampless": "^{{amplessVersion}}"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.7"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "ampless-plugin"
+  ],
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "{{nameKebab}}",
+    "trustLevel": "{{trustLevel}}",
+    "capabilities": [{{capabilitiesJsonArray}}],
+    "displayName": { "en": "{{DisplayName}}", "ja": "{{displayNameJa}}" }
+  }
+}

package/dist/templates/plugin-standalone/src/index.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest'
+import {{nameCamelCase}}Plugin from './index.js'
+
+describe('{{nameCamelCase}}Plugin', () => {
+  it('returns a plugin with the declared name + apiVersion', () => {
+    const plugin = {{nameCamelCase}}Plugin()
+    expect(plugin.name).toBe('{{nameKebab}}')
+    expect(plugin.apiVersion).toBe(1)
+    expect(plugin.trust_level).toBe('{{trustLevel}}')
+  })
+
+  it('honors an explicit instanceId', () => {
+    const plugin = {{nameCamelCase}}Plugin({ instanceId: 'custom-instance' })
+    expect(plugin.instanceId).toBe('custom-instance')
+  })
+})

package/dist/templates/plugin-standalone/src/index.ts

@@ -0,0 +1,29 @@
+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}}
+ */
+export default function {{nameCamelCase}}Plugin(
+  options: {{NameCamelCase}}Options = {}
+): AmplessPlugin {
+  const instanceId = options.instanceId ?? '{{nameKebab}}'
+  return definePlugin({
+    name: '{{nameKebab}}',
+    packageName: '{{packageName}}',
+    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:
+    //   https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md
+  })
+}

package/dist/templates/plugin-standalone/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src"]
+}

package/dist/templates/plugin-standalone/tsup.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ampless",
-  "version": "1.0.0-alpha.78",
+  "version": "1.0.0-alpha.79",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",