@jchat/create-addon 1.0.0-alpha.3 → 1.0.0-alpha.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @jchat/create-addon
 
+## 1.0.0-alpha.4
+
+### Patch Changes
+
+- 8b8297f: Rename package from `create-jchat-addon` to `@jchat/create-addon` and update binary script to `create-addon`.
+- 5bbb2b6: Inherit jchatVersion and addonSdkVersion directly from @jchat/create-addon package version when generating standalone devkit.
+
 ## 1.0.0-alpha.3
 
 ## 1.0.0-alpha.2

package/README.md

@@ -14,7 +14,7 @@ bunx @jchat/create-addon <addon-id>
 
 - `<addon-id>`: (Required) The unique ID for your addon, typically hyphenated (e.g., `weather-addon`).
 - `--target=<directory>`: (Optional) The directory to generate the workspace in. Defaults to `../<addon-id>` relative to the current working directory.
-- `--image=<image>`: (Optional) A specific Docker image to use for the sandbox environment. Defaults to `ghcr.io/mjjabarullah/addon-developer-sandbox`.
+- `--image=<image>`: (Optional) A specific Docker / Podman container image to use for the sandbox environment. Defaults to `ghcr.io/mjjabarullah/addon-developer-sandbox`.
 
 ### Example
 
@@ -26,7 +26,7 @@ cd my-addon
 ## Requirements
 
 - Bun 1.3+
-- Docker
+- Docker or Podman
 
 ## Licensing
 

package/dist/cli.mjs

@@ -18,9 +18,9 @@ async function runCreator(arguments_) {
 	const options = parseCreatorArguments(arguments_);
 	writeStandaloneDevkit({
 		...options,
-		jchatVersion: manifest.jchat.jchatVersion,
-		addonSdkVersion: manifest.jchat.addonSdkVersion,
-		sandboxImage: options.sandboxImage ?? `${manifest.jchat.sandboxImage}:${manifest.jchat.jchatVersion.replaceAll("+", "-")}`
+		jchatVersion: manifest.version,
+		addonSdkVersion: manifest.version,
+		sandboxImage: options.sandboxImage ?? `${manifest.jchat?.sandboxImage ?? "ghcr.io/mjjabarullah/addon-developer-sandbox"}:${manifest.version.replaceAll("+", "-")}`
 	});
 	return path.resolve(options.targetDir);
 }

package/dist/generator.mjs

@@ -1,6 +1,19 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 //#region ../addon-sdk/src/diagnostics.ts
+/**
+* Constructs a semantic version compatibility range covering all minor/patch versions of the
+* current major version.
+*
+* @example
+*   ```ts
+*   createCompatibleMajorRange("1.4.2") // returns ">=1.4.2 <2.0.0"
+*   ```
+*
+* @param version - Valid semver string (e.g. `"1.2.0"`).
+* @returns Semver range string matching the current major series (e.g. `">=1.2.0 <2.0.0"`).
+* @throws {@link Error} If the input is not a valid semantic version string.
+*/
 function createCompatibleMajorRange(version) {
 	try {
 		Bun.semver.order(version, version);
@@ -98,7 +111,7 @@ function createComposeFile() {
     ports:
       - "127.0.0.1:\${JCHAT_SANDBOX_PORT:-4317}:4317"
     volumes:
-      - ./addon:/app/addons-dev/\${JCHAT_SANDBOX_ADDON_ID:?Set addon id}:ro
+      - ./addon:/app/addons/\${JCHAT_SANDBOX_ADDON_ID:?Set addon id}:ro
       - sandbox_uploads:/app/uploads
     depends_on:
       db:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jchat/create-addon",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "private": false,
   "keywords": [
     "addon",
@@ -22,7 +22,6 @@
   },
   "files": [
     "dist",
-    "src",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -40,23 +39,21 @@
   },
   "scripts": {
     "build": "tsdown",
-    "lint": "oxlint . --config=../../oxlint.json",
+    "lint": "oxlint .",
     "format": "oxfmt . --write",
     "typecheck": "tsc --noEmit",
     "prepack": "bun run build"
   },
   "devDependencies": {
-    "@jchat/addon-sdk": "1.0.0-alpha.3",
-    "@types/node": "^26.1.2",
-    "bun-types": "^1.3.14",
+    "@jchat/addon-sdk": "workspace:*",
+    "@types/node": "catalog:",
+    "bun-types": "catalog:",
     "tsdown": "^0.22.14"
   },
   "engines": {
     "bun": ">=1.3.11"
   },
   "jchat": {
-    "jchatVersion": "1.0.0-alpha.0",
-    "addonSdkVersion": "0.0.1",
     "sandboxImage": "ghcr.io/mjjabarullah/addon-developer-sandbox"
   }
 }

package/src/cli.test.ts

@@ -1,30 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { parseCreatorArguments } from "./cli"
-
-describe("create-addon CLI", () => {
-  test("uses the addon id as the default target", () => {
-    expect(parseCreatorArguments(["weather-addon"])).toEqual({
-      addonId: "weather-addon",
-      targetDir: "weather-addon",
-      sandboxImage: undefined
-    })
-  })
-
-  test("accepts target and image overrides", () => {
-    expect(
-      parseCreatorArguments([
-        "weather-addon",
-        "--target=../weather-kit",
-        "--image=registry.example/sandbox:test"
-      ])
-    ).toEqual({
-      addonId: "weather-addon",
-      targetDir: "../weather-kit",
-      sandboxImage: "registry.example/sandbox:test"
-    })
-  })
-
-  test("requires an addon id", () => {
-    expect(() => parseCreatorArguments([])).toThrow("Usage: bunx @jchat/create-addon")
-  })
-})

package/src/cli.ts

@@ -1,55 +0,0 @@
-#!/usr/bin/env bun
-
-import * as path from "node:path"
-import { writeStandaloneDevkit } from "./generator"
-
-interface CreatorPackageManifest {
-  version: string
-  jchat: {
-    jchatVersion: string
-    addonSdkVersion: string
-    sandboxImage: string
-  }
-}
-
-export interface CreatorArguments {
-  addonId: string
-  targetDir: string
-  sandboxImage?: string
-}
-
-export function parseCreatorArguments(arguments_: readonly string[]): CreatorArguments {
-  const positional = arguments_.filter((argument) => !argument.startsWith("--"))
-  const addonId = positional[0]
-  if (addonId === undefined || addonId.startsWith("-")) {
-    throw new Error("Usage: bunx @jchat/create-addon <addon-id> [--target=<directory>] [--image=<image>]")
-  }
-  const targetArgument = arguments_.find((argument) => argument.startsWith("--target="))
-  const imageArgument = arguments_.find((argument) => argument.startsWith("--image="))
-  return {
-    addonId,
-    targetDir: targetArgument?.slice("--target=".length) || addonId,
-    sandboxImage: imageArgument?.slice("--image=".length) || undefined
-  }
-}
-
-export async function runCreator(arguments_: readonly string[]): Promise<string> {
-  const manifest = (await Bun.file(
-    new URL("../package.json", import.meta.url)
-  ).json()) as CreatorPackageManifest
-  const options = parseCreatorArguments(arguments_)
-  writeStandaloneDevkit({
-    ...options,
-    jchatVersion: manifest.jchat.jchatVersion,
-    addonSdkVersion: manifest.jchat.addonSdkVersion,
-    sandboxImage:
-      options.sandboxImage ??
-      `${manifest.jchat.sandboxImage}:${manifest.jchat.jchatVersion.replaceAll("+", "-")}`
-  })
-  return path.resolve(options.targetDir)
-}
-
-if (import.meta.main) {
-  const target = await runCreator(process.argv.slice(2))
-  console.log(`Created standalone addon development kit at ${target}`)
-}

package/src/generator.ts

@@ -1,428 +0,0 @@
-import type { AddonManifest } from "@jchat/addon-sdk"
-import { createCompatibleMajorRange } from "@jchat/addon-sdk/diagnostics"
-import * as fs from "node:fs"
-import * as path from "node:path"
-
-export interface StandaloneDevkitOptions {
-  addonId: string
-  targetDir: string
-  jchatVersion: string
-  addonSdkVersion: string
-  sandboxImage?: string
-}
-
-const ADDON_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
-const DEFAULT_SANDBOX_IMAGE = "ghcr.io/mjjabarullah/addon-developer-sandbox"
-
-export function createStandaloneDevkitFiles(
-  options: StandaloneDevkitOptions
-): Readonly<Record<string, string>> {
-  if (!ADDON_ID_PATTERN.test(options.addonId)) {
-    throw new Error("Addon id must contain lowercase letters, numbers, and hyphens")
-  }
-  const image =
-    options.sandboxImage ?? `${DEFAULT_SANDBOX_IMAGE}:${options.jchatVersion.replace(/\+/g, "-")}`
-  const manifest: AddonManifest = {
-    id: options.addonId,
-    name: toDisplayName(options.addonId),
-    version: "1.0.0",
-    description: `${toDisplayName(options.addonId)} addon for JChat`,
-    author: "Developer",
-    compatibility: {
-      jchat: createCompatibleMajorRange(options.jchatVersion),
-      addonSdk: createCompatibleMajorRange(options.addonSdkVersion)
-    },
-    frontend: {
-      bundle: "./ui.js",
-      mountPoints: ["chat-toolbar"]
-    },
-    permissions: []
-  }
-
-  return Object.freeze({
-    ".env.example": createEnvironmentFile(options.addonId, image),
-    ".gitignore": ["node_modules/", "addon/node_modules/", "addon/build/", ".env", ""].join("\n"),
-    "README.md": createReadme(options.addonId),
-    "docker-compose.yml": createComposeFile(),
-    "package.json": `${JSON.stringify(createRootPackage(options.addonId), null, 2)}\n`,
-    "scripts/devkit.ts": createLifecycleScript(),
-    "addon/package.json": `${JSON.stringify(
-      createAddonPackage(options.addonId, options.addonSdkVersion),
-      null,
-      2
-    )}\n`,
-    "addon/tsconfig.json": `${JSON.stringify(createTsConfig(), null, 2)}\n`,
-    "addon/vite.config.ts": createViteConfig(),
-    "addon/src/manifest.ts": createManifestSource(manifest),
-    "addon/src/tailwind.css": createTailwindSource(),
-    "addon/src/ui.tsx": createUiSource(manifest.name)
-  })
-}
-
-export function writeStandaloneDevkit(options: StandaloneDevkitOptions): void {
-  const targetDir = path.resolve(options.targetDir)
-  if (fs.existsSync(targetDir)) {
-    throw new Error(`Development kit target already exists: ${targetDir}`)
-  }
-
-  for (const [relativePath, contents] of Object.entries(createStandaloneDevkitFiles(options))) {
-    const target = path.join(targetDir, ...relativePath.split("/"))
-    fs.mkdirSync(path.dirname(target), { recursive: true })
-    fs.writeFileSync(target, contents)
-  }
-}
-
-function createEnvironmentFile(addonId: string, image: string): string {
-  return [
-    `JCHAT_SANDBOX_IMAGE=${image}`,
-    `JCHAT_SANDBOX_ADDON_ID=${addonId}`,
-    "JCHAT_SANDBOX_PORT=4317",
-    "JCHAT_SANDBOX_HTTP_MOCK_PORT=4318",
-    "JCHAT_SANDBOX_HTTP_MOCK_OFFLINE=false",
-    "JCHAT_SANDBOX_ADDON_HTTP_MOCK_URL=http://http-mock:4318",
-    ""
-  ].join("\n")
-}
-
-function createComposeFile(): string {
-  return `services:
-  sandbox:
-    image: \${JCHAT_SANDBOX_IMAGE:?Copy .env.example to .env}
-    restart: unless-stopped
-    environment:
-      NODE_ENV: development
-      JCHAT_PORT: "4317"
-      JCHAT_COOKIE_SECRET: addon-sandbox-cookie-secret
-      JCHAT_DATABASE_URL: postgresql://jchat:jchat@db:5432/jchat
-      JCHAT_REDIS_DATABASE_URL: redis://redis:6379
-      JCHAT_STORAGE_TYPE: LOCAL
-      JCHAT_BOT_NAME: Sandbox Bot
-      JCHAT_BOT_EMAIL: bot@sandbox.local
-      JCHAT_DOMAIN: localhost
-      JCHAT_SITE_URL: http://localhost:\${JCHAT_SANDBOX_PORT:-4317}
-      JCHAT_ROUTING_MODE: path
-      JCHAT_ADDON_ENCRYPTION_KEY: addon-sandbox-encryption-key
-      JCHAT_ADDON_HTTP_MOCK_URL: \${JCHAT_SANDBOX_ADDON_HTTP_MOCK_URL-http://http-mock:4318}
-    ports:
-      - "127.0.0.1:\${JCHAT_SANDBOX_PORT:-4317}:4317"
-    volumes:
-      - ./addon:/app/addons-dev/\${JCHAT_SANDBOX_ADDON_ID:?Set addon id}:ro
-      - sandbox_uploads:/app/uploads
-    depends_on:
-      db:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-      http-mock:
-        condition: service_healthy
-
-  http-mock:
-    image: \${JCHAT_SANDBOX_IMAGE:?Copy .env.example to .env}
-    entrypoint: ["/app/addon-http-mock"]
-    environment:
-      JCHAT_SANDBOX_HTTP_MOCK_PORT: "4318"
-      JCHAT_SANDBOX_HTTP_MOCK_OFFLINE: \${JCHAT_SANDBOX_HTTP_MOCK_OFFLINE:-false}
-    ports:
-      - "127.0.0.1:\${JCHAT_SANDBOX_HTTP_MOCK_PORT:-4318}:4318"
-    healthcheck:
-      test: ["CMD", "/app/addon-http-mock", "--healthcheck"]
-      interval: 2s
-      timeout: 3s
-      retries: 30
-
-  db:
-    image: postgres:18-alpine
-    environment:
-      POSTGRES_USER: jchat
-      POSTGRES_PASSWORD: jchat
-      POSTGRES_DB: jchat
-    volumes:
-      - sandbox_postgres:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U jchat"]
-      interval: 2s
-      timeout: 3s
-      retries: 30
-
-  redis:
-    image: redis:8.0.6-alpine3.21
-    volumes:
-      - sandbox_redis:/data
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 2s
-      timeout: 3s
-      retries: 30
-
-volumes:
-  sandbox_postgres:
-  sandbox_redis:
-  sandbox_uploads:
-`
-}
-
-function createRootPackage(addonId: string) {
-  return {
-    name: `${addonId}-development-kit`,
-    private: true,
-    type: "module",
-    workspaces: ["addon"],
-    scripts: {
-      sandbox: "bun run ./scripts/devkit.ts run",
-      "sandbox:test": "bun run ./scripts/devkit.ts test",
-      "sandbox:reset": "bun run ./scripts/devkit.ts reset",
-      "sandbox:package": "bun run ./scripts/devkit.ts package",
-      "sandbox:cleanup": "bun run ./scripts/devkit.ts cleanup"
-    },
-    devDependencies: {
-      "bun-types": "^1.3.14"
-    },
-    engines: {
-      bun: ">=1.3.11"
-    }
-  }
-}
-
-function createAddonPackage(addonId: string, addonSdkVersion: string) {
-  return {
-    name: `@jchat/${addonId}`,
-    version: "1.0.0",
-    private: true,
-    type: "module",
-    scripts: {
-      dev: "vite build --watch --mode=development",
-      build: "vite build --mode=production",
-      test: "bun test",
-      typecheck: "tsc --noEmit"
-    },
-    dependencies: {
-      "@jchat/addon-sdk": `^${addonSdkVersion}`,
-      "@tanstack/react-query": "^5.101.4",
-      react: "^19.2.8",
-      "react-dom": "^19.2.8"
-    },
-    devDependencies: {
-      "@tailwindcss/vite": "^4.3.3",
-      "@types/node": "^26.1.1",
-      "@types/react": "^19.2.17",
-      "@types/react-dom": "^19.2.3",
-      "bun-types": "^1.3.14",
-      tailwindcss: "^4.3.3",
-      typescript: "^7.0.2",
-      vite: "^8.1.5"
-    }
-  }
-}
-
-function createTsConfig() {
-  return {
-    compilerOptions: {
-      strict: true,
-      target: "ESNext",
-      module: "ESNext",
-      moduleResolution: "bundler",
-      jsx: "react-jsx",
-      noEmit: true,
-      types: ["bun-types", "node"]
-    },
-    include: ["src/**/*.ts", "src/**/*.tsx", "vite.config.ts"]
-  }
-}
-
-function createManifestSource(manifest: AddonManifest): string {
-  return `import type { AddonManifest } from "@jchat/addon-sdk"
-
-const manifest: AddonManifest = ${JSON.stringify(manifest, null, 2)}
-
-export default manifest
-`
-}
-
-function createViteConfig(): string {
-  return `import { jchatAddon } from "@jchat/addon-sdk/vite"
-import tailwindcss from "@tailwindcss/vite"
-import path from "node:path"
-import { defineConfig } from "vite"
-import manifest from "./src/manifest"
-
-export default defineConfig({
-  plugins: [tailwindcss(), jchatAddon({ manifest })],
-  build: {
-    outDir: "build",
-    emptyOutDir: true,
-    lib: {
-      entry: path.resolve(import.meta.dirname, "src/ui.tsx"),
-      formats: ["es"],
-      fileName: () => "ui.[hash].js"
-    },
-    rolldownOptions: {
-      external: [
-        "react",
-        "react-dom",
-        "react/jsx-runtime",
-        "@tanstack/react-query",
-        "@jchat/addon-sdk"
-      ],
-      output: {
-        format: "esm"
-      }
-    }
-  }
-})
-`
-}
-
-function createUiSource(name: string): string {
-  return `import type { AddonProps } from "@jchat/addon-sdk"
-import { useAddonSDK, useIcons } from "@jchat/addon-sdk"
-import "./tailwind.css"
-
-export default function Addon({ mountPoint }: AddonProps) {
-  const sdk = useAddonSDK()
-  const { Icons } = useIcons()
-
-  return (
-    <div className="rounded border border-border bg-card p-2 text-card-foreground">
-      <div className="mb-2 flex items-center gap-2">
-        <Icons.Plus aria-hidden="true" className="size-4 text-primary" />
-        <strong>${name}</strong>
-      </div>
-      <p className="mb-2 text-sm text-muted-foreground">Mounted at {mountPoint}</p>
-      <button
-        type="button"
-        className="rounded bg-primary px-3 py-2 text-primary-foreground"
-        onClick={() => sdk.toast("Hello from ${name}")}
-      >
-        Test addon
-      </button>
-    </div>
-  )
-}
-`
-}
-
-function createTailwindSource(): string {
-  return `@import "tailwindcss";
-
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-border: var(--border);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-muted-foreground: var(--muted-foreground);
-}
-`
-}
-
-function createLifecycleScript(): string {
-  return `import * as fs from "node:fs"
-import * as path from "node:path"
-
-type Command = "run" | "test" | "reset" | "package" | "cleanup"
-
-const command = (process.argv[2] ?? "run") as Command
-if (!["run", "test", "reset", "package", "cleanup"].includes(command)) {
-  throw new Error(\`Unknown development-kit command: \${command}\`)
-}
-
-const root = path.resolve(import.meta.dir, "..")
-const environment = {
-  ...process.env,
-  ...readEnvironment(path.join(root, ".env"))
-}
-const addonId = environment.JCHAT_SANDBOX_ADDON_ID
-if (!addonId) throw new Error("JCHAT_SANDBOX_ADDON_ID is missing from .env")
-const compose = [
-  "docker",
-  "compose",
-  "--project-name",
-  \`jchat-addon-devkit-\${addonId}\`,
-  "--file",
-  path.join(root, "docker-compose.yml")
-]
-
-if (command === "test") {
-  await run(["bun", "test"], path.join(root, "addon"), environment)
-} else if (command === "package") {
-  await run(["bun", "run", "build"], path.join(root, "addon"), environment)
-} else if (command === "cleanup") {
-  await run([...compose, "down", "--remove-orphans", "--volumes"], root, environment)
-} else {
-  if (command === "reset") {
-    await run([...compose, "down", "--remove-orphans", "--volumes"], root, environment)
-  }
-  await run(["bun", "run", "build"], path.join(root, "addon"), environment)
-  const watcher = Bun.spawn(["bun", "run", "dev"], {
-    cwd: path.join(root, "addon"),
-    env: environment,
-    stdout: "inherit",
-    stderr: "inherit"
-  })
-  try {
-    await run([...compose, "up"], root, environment)
-  } finally {
-    watcher.kill()
-    await watcher.exited
-  }
-}
-
-async function run(command: string[], cwd: string, env: Record<string, string | undefined>) {
-  const child = Bun.spawn(command, { cwd, env, stdin: "inherit", stdout: "inherit", stderr: "inherit" })
-  const exitCode = await child.exited
-  if (exitCode !== 0) throw new Error(\`\${command.join(" ")} exited with code \${exitCode}\`)
-}
-
-function readEnvironment(file: string): Record<string, string> {
-  if (!fs.existsSync(file)) throw new Error("Copy .env.example to .env before running the kit")
-  return Object.fromEntries(
-    fs.readFileSync(file, "utf8")
-      .split(/\\r?\\n/)
-      .filter((line) => line && !line.startsWith("#"))
-      .map((line) => {
-        const separator = line.indexOf("=")
-        return [line.slice(0, separator), line.slice(separator + 1)]
-      })
-  )
-}
-`
-}
-
-function createReadme(addonId: string): string {
-  return `# ${toDisplayName(addonId)} Development Kit
-
-This workspace develops \`${addonId}\` against the license-free JChat developer sandbox without
-including JChat Core source.
-
-## Start
-
-\`\`\`powershell
-Copy-Item .env.example .env
-bun install
-bun sandbox
-\`\`\`
-
-Open \`http://127.0.0.1:4317\`. The HTTP fixture recorder is available at
-\`http://127.0.0.1:4318/requests\`.
-
-## Commands
-
-- \`bun sandbox\`
-- \`bun sandbox:test\`
-- \`bun sandbox:reset\`
-- \`bun sandbox:package\`
-- \`bun sandbox:cleanup\`
-
-The referenced JChat packages and sandbox image must be published before this standalone kit can
-install or start outside the JChat repository.
-`
-}
-
-function toDisplayName(addonId: string): string {
-  return addonId
-    .split("-")
-    .map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`)
-    .join(" ")
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-export {
-  createStandaloneDevkitFiles,
-  writeStandaloneDevkit,
-  type StandaloneDevkitOptions
-} from "./generator"