flare-plugin-sdk 0.1.0-beta.1 → 0.1.0-beta.4

package/README.md

@@ -1,12 +1,42 @@
 # Flare Plugin SDK
 
-`flare-plugin-sdk` contains editor types, a local package command,
+`flare-plugin-sdk` contains a project initializer, editor types, a local package command,
 templates, examples, and a portable AI authoring skill for Social Plugin API v1.
 Flare provides the plugin runtime. Supported targets are Android, JVM Desktop,
 iOS, and native macOS, not Web. Use a Flare build that includes Plugins in Settings;
 this SDK does not promise a minimum public app release.
 
-## Install for development
+## Create a plugin
+
+With Node 22 or newer, run:
+
+```sh
+npx flare-plugin-sdk@next init my-plugin
+```
+
+This copies the GitHub template bundled with that SDK version into `my-plugin`:
+
+```text
+my-plugin/
+  manifest.json
+  plugin.js
+  assets/icon.png
+  README.md
+```
+
+The directory name becomes the plugin and platform display name. The initializer
+generates unique plugin/platform IDs; keep them stable after publication. New and
+empty directories are accepted, including `init .` in an empty current directory.
+Non-empty directories, files, and symbolic links are rejected without overwriting
+them. The command uses bundled files only and does not install dependencies,
+initialize Git, contact your website, or publish anything. Run
+`npx flare-plugin-sdk@next --help` for usage.
+
+Adapt the illustrative API endpoints, replace the placeholder icon, and follow
+the generated README. In Desktop or native macOS, select the generated directory
+in Settings → Plugins → Plugin development to validate and reload it.
+
+## Install for editor types and packaging
 
 Install the npm preview:
 
@@ -29,9 +59,10 @@ These local checks and packaging commands do not publish anything.
 
 ## Create and develop a plugin
 
-1. Copy the contents of `node_modules/flare-plugin-sdk/skill/flare-plugin/assets/github-template/`
-   into your plugin repository. Replace its IDs, icon, and illustrative website
-   endpoints using evidence from the real API.
+1. Create a plugin with the initializer above, or manually copy the contents of
+   `node_modules/flare-plugin-sdk/skill/flare-plugin/assets/github-template/` into
+   your repository. Manual copies retain example IDs and names; replace them.
+   Adapt the icon and illustrative website endpoints using evidence from the real API.
 2. Read the [complete developer guide](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin).
    The same guide is bundled at `skill/flare-plugin/README.md` inside the npm package,
    with all authentication, capability, runtime, data, testing, and publication references.
@@ -43,7 +74,7 @@ These local checks and packaging commands do not publish anything.
 5. For local file installation, package that directory from your plugin project:
 
    ```sh
-   npx flare-plugin-pack ./dist ./plugin.fpp
+   npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ./plugin.fpp
    ```
 
 The packer accepts plugin files only, so keep source, `.git`, `package.json`,
@@ -85,9 +116,11 @@ All documentation is in English. The complete Pixelfed adapter is bundled at
 
 From `feature/plugin/sdk`, run `npm ci` and `npm test` with Node 22 or newer.
 The tests build an npm tarball, check its complete resource set and license,
-install it offline in an empty project, type-check an actual consumer, and run
-the installed package command against the bundled template. They do not contact
-a website or publish to npm. Flare's Host and platform acceptance checks are
+install it offline in an empty project, invoke the actual npx initializer,
+type-check a consumer, and package both the generated project and bundled template.
+Initializer tests cover valid unique IDs, empty/nested/Unicode paths, invalid
+arguments, and preserving existing directories, files, and symlinks. They do not
+contact a website or publish to npm. Flare's Host and platform acceptance checks are
 documented in `skill/flare-plugin/references/testing.md`.
 
 ## Publish this SDK (maintainers)
@@ -121,12 +154,12 @@ Public OIDC publications from this public repository receive provenance automati
 For subsequent releases:
 
 1. Update the SDK version and lockfile together, for example with
-   `npm version 0.1.0-beta.2 --no-git-tag-version`, and commit the tested changes.
-2. Tag that commit `plugin-sdk-v0.1.0-beta.2` and push only that tag when ready to publish.
+   `npm version prerelease --preid beta --no-git-tag-version`, and commit the tested changes.
+2. Tag that commit `plugin-sdk-v<version>` using the new version and push only that tag when ready to publish.
    The workflow rejects a tag that does not exactly match `package.json`.
 3. The workflow validates the tarball first, then publishes prereleases to `next`
    and stable versions to `latest`. Existing app workflows exclude SDK tags.
 
-The **Plugin SDK** workflow runs validation on relevant pull requests. Its manual
-**Run workflow** action also validates only, even when a tag is selected; publishing
-requires a push of a matching `plugin-sdk-v*` tag. Updating a PR never publishes npm.
+Run the **Plugin SDK** workflow manually to validate a branch or tag; this does not
+publish, even when a tag is selected. Publishing requires a push of a matching
+`plugin-sdk-v*` tag. Branch pushes and pull requests do not start this workflow.

package/bin/cli.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+import { cp, lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const usage = "Usage: flare-plugin-sdk init <directory>";
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(usage);
+    return;
+  }
+  if (args.length !== 2 || args[0] !== "init" || !args[1] || args[1].startsWith("-")) {
+    throw new Error(usage);
+  }
+
+  const target = resolve(args[1]);
+  const name = basename(target);
+  if (!name.trim() || /[\u0000-\u001f\u007f]/.test(args[1])) {
+    throw new Error("Choose a directory name without control characters or blank text");
+  }
+  const metadata = await lstat(target).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  if (metadata && (!metadata.isDirectory() || metadata.isSymbolicLink() || (await readdir(target)).length)) {
+    throw new Error("Destination must be a new or empty directory, not a file or symbolic link");
+  }
+
+  const template = fileURLToPath(new URL("../skill/flare-plugin/assets/github-template/", import.meta.url));
+  const manifestPath = join(template, "manifest.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  const identity = randomUUID().replaceAll("-", "");
+  manifest.id = `local.plugin.p${identity}`;
+  manifest.name = name;
+  manifest.platform.id = `Plugin${identity}`;
+  manifest.platform.name = name;
+
+  await mkdir(target, { recursive: true });
+  for (const entry of await readdir(template)) {
+    if (entry === "manifest.json") continue;
+    await cp(join(template, entry), join(target, entry), {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+    });
+  }
+  await writeFile(join(target, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+
+  console.log(`Created ${target}\nPlugin ID: ${manifest.id}\nPlatform ID: ${manifest.platform.id}`);
+  console.log("Adapt the example API in plugin.js and README.md, then load this directory in Flare's Plugin development.");
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flare-plugin-sdk",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.4",
   "description": "Types, tooling, templates and authoring references for Flare plugins",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/DimensionDev/Flare#plugins-beta",
@@ -13,10 +13,12 @@
     "url": "https://github.com/DimensionDev/Flare/issues"
   },
   "bin": {
+    "flare-plugin-sdk": "bin/cli.mjs",
     "flare-plugin-pack": "skill/flare-plugin/pack.mjs"
   },
   "types": "skill/flare-plugin/flare-plugin.d.ts",
   "files": [
+    "bin/",
     "skill/flare-plugin/"
   ],
   "engines": {