@picloom/create-plugin 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lllei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @picloom/create-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create a standalone Picloom plugin project with Bun 1.4.3+. No main repository
+checkout, Node.js or npm CLI is required.
+
+Create a project:
+
+```sh
+bun create @picloom/plugin@0.1.1 ./my-plugin
+```
+
+The destination must not exist; its parent must exist. `--help` prints usage.
+The tool copies a date path plugin template and prints next steps. It does not
+install dependencies, start a service, or publish anything. Follow the generated
+README to edit, build and install the plugin.
+
+See [quick start](https://llleixx.github.io/picloom/development/plugin-tooling.html)
+for the full workflow and optional local tarball usage. Package
+maintainers use [tool maintenance](https://github.com/llleixx/picloom/blob/main/docs/development/plugin-tooling-maintenance.md).
+
+## 中文
+
+使用 Bun 1.4.3+ 创建独立插件项目，无需主仓库、Node.js 或 npm CLI。
+使用上方命令创建项目，完整流程与可选本地压缩包用法见
+[快速开始](https://llleixx.github.io/picloom/development/plugin-tooling.html#本地压缩包)。
+
+目标目录必须不存在，父目录必须存在。工具只复制日期路径插件模板并提示下一步，
+不安装依赖、不启动服务、不发布代码。生成后按项目内 README 修改、构建和安装插件。
+
+Generated projects use `@picloom/plugin-sdk` for contracts and runtime helpers, and `@picloom/plugin-tools` for ZIP builds. No build script is copied. Use creator 0.1.1, tools 0.1.0 and plugin SDK 0.1.0.
+
+生成项目依赖 SDK 与开发工具包，不复制构建实现；使用脚手架 0.1.1、工具 0.1.0 和插件 SDK 0.1.0 的 npm 精确版本。

package/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun
+import {
+  cp,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  writeFile,
+} from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+if (args.length === 1 && ["--help", "-h"].includes(args[0])) {
+  console.log("Usage: bun create @picloom/plugin <new-directory>");
+} else if (args.length !== 1 || args[0].startsWith("-")) {
+  console.error("Usage: bun create @picloom/plugin <new-directory>");
+  process.exitCode = 1;
+} else {
+  try {
+    const target = resolve(args[0]);
+    // Refuse even empty existing directories: never merge into a user's project.
+    await mkdir(target);
+    const template = fileURLToPath(new URL("./template/", import.meta.url));
+    for (const entry of await readdir(template)) {
+      await cp(resolve(template, entry), resolve(target, entry), {
+        recursive: true,
+        force: false,
+        errorOnExist: true,
+      });
+    }
+    // Package managers may rename/omit .gitignore when packing, so ship it under a plain name.
+    await rename(resolve(target, "gitignore"), resolve(target, ".gitignore"));
+    const name =
+      basename(target)
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]/g, "-")
+        .replace(/^[^a-z]+/, "")
+        .slice(0, 80) || "my-plugin";
+    const manifestPath = resolve(target, "plugin.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    manifest.id = `example.${name}`;
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    const packagePath = resolve(target, "package.json");
+    const pkg = JSON.parse(await readFile(packagePath, "utf8"));
+    pkg.name = name;
+    await writeFile(packagePath, JSON.stringify(pkg, null, 2) + "\n");
+    console.log(
+      `Created ${target}\n\nNext:\n  cd ${JSON.stringify(args[0])}\n  bun install\n  bun run typecheck\n  bun run build\n\nUpload dist/${manifest.id}-${manifest.version}.zip to Picloom.`,
+    );
+  } catch (error) {
+    console.error(
+      error.code === "EEXIST"
+        ? "Target already exists. Choose a new directory; no existing files were changed."
+        : `Could not create plugin: ${error.message}`,
+    );
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@picloom/create-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Create a standalone Picloom plugin project",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-plugin": "./index.js"
+  },
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "files": [
+    "index.js",
+    "template",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llleixx/picloom-tooling.git",
+    "directory": "tools/create-plugin"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lllei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/README.md

@@ -0,0 +1,71 @@
+# My Picloom plugin
+
+A standalone plugin project using Bun 1.4.3+ and Picloom plugin API 1. Use a
+separate Picloom 0.1.0 development test instance for installation and uploads.
+Node.js and npm CLI are not required.
+
+## Develop
+
+```sh
+bun install
+bun run typecheck
+bun run build
+```
+
+Commit the generated `bun.lock`. To check types without building, run
+`bun run typecheck`. Type checking and ZIP building are separate commands under Bun. Builds call `@picloom/plugin-tools`; no build implementation is copied into the project.
+
+- `plugin.json`: plugin ID, version, kind and API version. Replace the
+  generated `example.*` ID with your own stable ID before sharing.
+- `src/index.ts`: localized display text (`defaultLocale` and `messages`), configuration and implementation. It reads identity fields from
+  the manifest and initially generates UTC date paths. It omits `configSchema`
+  because it has no custom configuration; the host accepts only `{}`.
+- `package.json`: development dependencies and commands; its version is not the
+  plugin version. The project is private to prevent accidental npm publication.
+- `dist/<plugin-id>-<version>.zip`: build output, containing `plugin.json` and
+  bundled `index.js` at the ZIP root. No system `zip` command is required.
+
+Build loads your entry to check its identity, so keep module top-level code free
+of external side effects. Sharp is a development dependency for SDK types;
+use `services.images.sharp` at runtime. The template bundles JavaScript only;
+extra assets and native modules require explicit packaging.
+
+## Install and update
+
+1. Sign in to the test instance as Owner and upload the ZIP in plugin management.
+2. Review the identity, confirm trust, and check that the plugin loaded.
+3. Select your path plugin in a test upload profile with an available storage group.
+4. Upload a PNG and open its returned link. The starter path contains the UTC date
+   and file ID, plus the profile's public prefix.
+5. After code changes, increment `plugin.json`'s version, rebuild and install.
+   In the profile choose the new version, preview and apply the upgrade.
+
+Installation does not activate a plugin automatically. Same-version replacement
+and source hot reload are not supported. See [packaging and upgrades](https://llleixx.github.io/picloom/development/plugin-release.html)
+for configuration migrations and dependency restrictions.
+
+For other plugin types and adapting the examples, follow
+[quick start](https://llleixx.github.io/picloom/development/plugin-tooling.html#使用教程示例).
+See [host services](https://llleixx.github.io/picloom/development/plugin-services.html)
+for configuration, secrets and state, and [errors and concurrency](https://llleixx.github.io/picloom/development/plugin-errors.html)
+for retries, cancellation and instance lifecycle.
+
+## 中文
+
+本项目只需 Bun 1.4.3+。修改 `plugin.json` 的身份信息和 `src/index.ts` 的实现，
+执行 `bun install`、`bun run build`，将生成的 `bun.lock` 提交到自己的插件仓库。
+类型检查单独运行 `bun run typecheck`；构建调用 `@picloom/plugin-tools` 输出 `dist/<插件ID>-<版本>.zip`，无需系统 `zip` 命令。
+
+用 Owner 账号在独立测试实例中安装 ZIP，确认加载成功后，在上传配置中选择插件并
+关联可用存储组。上传 PNG，确认日期路径和公开链接。改代码后增加清单版本，重新
+构建安装，再选择新版本、预览并应用升级；安装新版不会自动切换已有配置。
+
+模板没有自定义配置项，因此省略 `configSchema`，宿主只接受空配置 `{}`；添加配置项时再声明对象 Schema。
+
+名称和简介通过 `nameKey/descriptionKey` 引用入口的 `messages` 字典，`defaultLocale` 指定内容默认语言。
+入口从清单读取身份字段；`package.json` 的版本不是插件版本。构建会加载入口，
+不要在模块顶层执行远端操作。Sharp 的开发依赖提供类型，运行时使用宿主实例。
+其他类型和完整接口见上方文档链接。
+
+The current creator/tool versions are not yet published; use their local tarballs for validation.
+当前脚手架和工具版本尚未发布，请使用本地压缩包验证。

package/template/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.env
+.env.*

package/template/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "my-plugin",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "bun run --bun tsc --noEmit",
+    "build": "bun --bun picloom-plugin build"
+  },
+  "devDependencies": {
+    "@picloom/plugin-sdk": "0.1.0",
+    "@types/bun": "1.3.10",
+    "sharp": "0.34.5",
+    "typescript": "5.9.3",
+    "@picloom/plugin-tools": "0.1.0"
+  },
+  "engines": {
+    "bun": ">=1.4.3"
+  }
+}

package/template/plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "example.my-plugin",
+  "version": "0.1.0",
+  "kind": "path",
+  "apiVersion": 1,
+  "entry": "index.js"
+}

package/template/src/index.ts

@@ -0,0 +1,40 @@
+import { PluginError, type Definition } from "@picloom/plugin-sdk";
+import manifest from "../plugin.json";
+
+// Narrow JSON strings through validation, rather than duplicating identity values.
+const { kind, apiVersion } = manifest;
+if (kind !== "path" || apiVersion !== 1)
+  throw new Error("This implementation requires kind=path and apiVersion=1");
+
+export default {
+  id: manifest.id,
+  defaultLocale: "en-US",
+  nameKey: "package.name",
+  messages: { "en-US": { "package.name": "My date path" } },
+  version: manifest.version,
+  kind,
+  apiVersion,
+  configSchemaVersion: 1,
+  async createInstance() {
+    return {
+      async generate({ fileId, uploadedAt, metadata }) {
+        const extensions: Record<string, string> = {
+          "image/jpeg": "jpg",
+          "image/png": "png",
+          "image/gif": "gif",
+          "image/webp": "webp",
+          "image/avif": "avif",
+          "image/svg+xml": "svg",
+        };
+        const extension = extensions[metadata.mimeType ?? ""];
+        if (!extension)
+          throw new PluginError("UNSUPPORTED", "Unsupported image format");
+        const date = new Date(uploadedAt)
+          .toISOString()
+          .slice(0, 10)
+          .replaceAll("-", "/");
+        return { logicalKey: `${date}/${fileId}.${extension}` };
+      },
+    };
+  },
+} satisfies Definition<"path">;

package/template/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "types": [
+      "bun"
+    ],
+    "skipLibCheck": false
+  },
+  "include": [
+    "src/**/*.ts",
+    "plugin.json"
+  ]
+}