create-chronicler-grimoire 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chronicler community
+
+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/bin.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// create-chronicler-grimoire — scaffold a new Chronicler Grimoire plugin.
+//
+//   npx create-chronicler-grimoire my-plugin
+//
+// Interactive prompts for the manifest fields, picks a template based on
+// which surfaces the plugin will use, writes the scaffold to ./<name>/,
+// runs npm install. From `npx ...` to "edit index.ts and install" should
+// be under 60 seconds.
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline/promises";
+import { spawn } from "node:child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, "templates");
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+async function ask(question, defaultValue) {
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  const answer = (await rl.question(`${question}${suffix}: `)).trim();
+  return answer || defaultValue || "";
+}
+
+async function askChoice(question, choices) {
+  const list = choices.map((c, i) => `  ${i + 1}) ${c}`).join("\n");
+  const answer = await rl.question(`${question}\n${list}\nChoice (1-${choices.length}): `);
+  const idx = parseInt(answer.trim(), 10) - 1;
+  if (idx < 0 || idx >= choices.length) {
+    console.log("Invalid choice, defaulting to first option.");
+    return choices[0];
+  }
+  return choices[idx];
+}
+
+function slug(s) {
+  return s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+async function copyTemplate(src, dest, replacements) {
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, applyReplacements(entry.name, replacements));
+    if (entry.isDirectory()) {
+      await fs.mkdir(destPath, { recursive: true });
+      await copyTemplate(srcPath, destPath, replacements);
+    } else {
+      const content = await fs.readFile(srcPath, "utf8");
+      await fs.writeFile(destPath, applyReplacements(content, replacements));
+    }
+  }
+}
+
+function applyReplacements(s, replacements) {
+  let out = s;
+  for (const [key, value] of Object.entries(replacements)) {
+    out = out.replaceAll(`{{${key}}}`, value);
+  }
+  return out;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const initialName = argv[0];
+
+  console.log("\n⚗  create-chronicler-grimoire\n");
+
+  const name = await ask("Plugin directory name", initialName ?? "my-grimoire");
+  const targetDir = path.resolve(process.cwd(), name);
+  if (existsSync(targetDir)) {
+    console.error(`✗ Directory ${targetDir} already exists. Pick a different name.`);
+    rl.close();
+    process.exit(1);
+  }
+
+  const id = await ask("Plugin id (reverse-DNS)", `io.example.${slug(name)}`);
+  const displayName = await ask("Display name", name.replace(/[-_]/g, " "));
+  const description = await ask("One-line description", `${displayName} — a Chronicler Grimoire plugin`);
+  const author = await ask("Author", "");
+  const license = await ask("License", "MIT");
+
+  const template = await askChoice("Pick a template", [
+    "hook-only (afterChat observer)",
+    "slash-command (with /command)",
+    "ui-slot (inspector:tab React component)",
+    "full (hook + slash + UI)",
+  ]);
+  const templateKey = template.split(" ")[0]; // hook-only / slash-command / ui-slot / full
+
+  const replacements = {
+    PLUGIN_ID: id,
+    PLUGIN_NAME: displayName,
+    PLUGIN_DESCRIPTION: description,
+    PLUGIN_AUTHOR: author,
+    PLUGIN_LICENSE: license,
+  };
+
+  console.log(`\nScaffolding ${targetDir}…`);
+  await fs.mkdir(targetDir, { recursive: true });
+  await copyTemplate(path.join(TEMPLATES_DIR, templateKey), targetDir, replacements);
+
+  console.log(`✓ Scaffold written.\n`);
+  console.log(`Next steps:`);
+  console.log(`  cd ${name}`);
+  console.log(`  npm install`);
+  console.log(`  # edit index.ts`);
+  console.log(`  cp -r . ~/.chronicler/plugins/${name}    # install locally`);
+  console.log(`  # or push to github and use the Browse Grimoire UI to install via URL\n`);
+
+  const install = (await ask("Run npm install now? (y/n)", "y")).toLowerCase();
+  if (install === "y" || install === "yes") {
+    await new Promise((resolve) => {
+      const child = spawn("npm", ["install"], {
+        cwd: targetDir,
+        stdio: "inherit",
+      });
+      child.on("close", resolve);
+    });
+  }
+
+  rl.close();
+}
+
+main().catch((e) => {
+  console.error(e);
+  rl.close();
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "create-chronicler-grimoire",
+  "version": "0.1.0",
+  "description": "Scaffold a new Chronicler Grimoire plugin in seconds",
+  "bin": {
+    "create-chronicler-grimoire": "./bin.mjs"
+  },
+  "type": "module",
+  "files": [
+    "bin.mjs",
+    "templates"
+  ],
+  "keywords": ["chronicler", "grimoire", "scaffold", "cli"],
+  "license": "MIT",
+  "homepage": "https://github.com/yantrikos/chronicler/tree/main/packages/create-grimoire",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yantrikos/chronicler.git",
+    "directory": "packages/create-grimoire"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/full/Panel.tsx

@@ -0,0 +1,25 @@
+interface Props {
+  pluginId: string;
+  characterId: string | null;
+}
+
+export function Panel({ pluginId, characterId }: Props) {
+  return (
+    <div className="h-full overflow-y-auto p-4 text-xs text-neutral-300">
+      <header className="mb-3">
+        <h2 className="text-sm font-semibold text-neutral-100 mb-0.5">
+          {{PLUGIN_NAME}}
+        </h2>
+        <p className="text-[11px] text-neutral-500">
+          Plugin <code className="text-emerald-400">{pluginId}</code>{" "}
+          {characterId && (
+            <>· active: <code className="text-neutral-200">{characterId}</code></>
+          )}
+        </p>
+      </header>
+      <p className="text-neutral-400 leading-relaxed">
+        Edit <code>Panel.tsx</code> to make this panel useful.
+      </p>
+    </div>
+  );
+}

package/templates/full/README.md

@@ -0,0 +1,26 @@
+# {{PLUGIN_NAME}}
+
+{{PLUGIN_DESCRIPTION}}
+
+A [Chronicler Grimoire](https://github.com/yantrikos/chronicler) plugin.
+
+## Install
+
+Drop into your Chronicler plugins directory:
+
+```bash
+git clone <repo-url> ~/.chronicler/plugins/{{PLUGIN_ID}}
+```
+
+Or paste the repo URL into the Browse Grimoire modal in the Chronicler UI.
+
+## Develop
+
+```bash
+npm install
+# edit index.ts
+```
+
+## License
+
+{{PLUGIN_LICENSE}}

package/templates/full/grimoire.json

@@ -0,0 +1,20 @@
+{
+  "id": "{{PLUGIN_ID}}",
+  "name": "{{PLUGIN_NAME}}",
+  "version": "0.1.0",
+  "apiVersion": "^0.1.0",
+  "description": "{{PLUGIN_DESCRIPTION}}",
+  "author": "{{PLUGIN_AUTHOR}}",
+  "license": "{{PLUGIN_LICENSE}}",
+  "permissions": {
+    "network": [],
+    "filesystem": "plugin-data-only",
+    "llm": false,
+    "memory": false
+  },
+  "contributes": {
+    "hooks": [{ "point": "afterWrite", "type": "observer" }],
+    "commands": ["status"],
+    "ui": { "slots": ["inspector:tab"] }
+  }
+}

package/templates/full/index.ts

@@ -0,0 +1,52 @@
+import { defineGrimoire, type GrimoireManifest } from "@chronicler/grimoire";
+import { Panel } from "./Panel";
+
+export const manifest: GrimoireManifest = {
+  id: "{{PLUGIN_ID}}",
+  name: "{{PLUGIN_NAME}}",
+  version: "0.1.0",
+  apiVersion: "^0.1.0",
+  description: "{{PLUGIN_DESCRIPTION}}",
+  author: "{{PLUGIN_AUTHOR}}",
+  license: "{{PLUGIN_LICENSE}}",
+  permissions: {
+    network: [],
+    filesystem: "plugin-data-only",
+    llm: false,
+    memory: false,
+  },
+  contributes: {
+    hooks: [{ point: "afterWrite", type: "observer" }],
+    commands: ["status"],
+    ui: { slots: ["inspector:tab"] },
+  },
+};
+
+export default defineGrimoire({
+  id: "{{PLUGIN_ID}}",
+
+  setup(ctx) {
+    let turnCount = 0;
+
+    ctx.hooks.afterWrite.observe(async (event, api) => {
+      turnCount++;
+      await api.storage.set("turnCount", turnCount);
+    });
+
+    ctx.commands.register({
+      name: "status",
+      description: "Show plugin status",
+      run: async (_args, api) => {
+        const count = (await api.storage.get<number>("turnCount")) ?? 0;
+        return {
+          kind: "system",
+          content: `📊 {{PLUGIN_NAME}} has observed ${count} turn${count === 1 ? "" : "s"}`,
+        };
+      },
+    });
+
+    ctx.ui.registerSlot("inspector:tab", Panel, { title: "{{PLUGIN_NAME}}" });
+
+    return {};
+  },
+});

package/templates/full/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{PLUGIN_ID}}",
+  "version": "0.1.0",
+  "description": "{{PLUGIN_DESCRIPTION}}",
+  "type": "module",
+  "main": "index.ts",
+  "author": "{{PLUGIN_AUTHOR}}",
+  "license": "{{PLUGIN_LICENSE}}",
+  "devDependencies": {
+    "@chronicler/grimoire": "^0.1.0",
+    "typescript": "~5.8.3"
+  }
+}

package/templates/hook-only/README.md

@@ -0,0 +1,26 @@
+# {{PLUGIN_NAME}}
+
+{{PLUGIN_DESCRIPTION}}
+
+A [Chronicler Grimoire](https://github.com/yantrikos/chronicler) plugin.
+
+## Install
+
+Drop into your Chronicler plugins directory:
+
+```bash
+git clone <repo-url> ~/.chronicler/plugins/{{PLUGIN_ID}}
+```
+
+Or paste the repo URL into the Browse Grimoire modal in the Chronicler UI.
+
+## Develop
+
+```bash
+npm install
+# edit index.ts
+```
+
+## License
+
+{{PLUGIN_LICENSE}}

package/templates/hook-only/grimoire.json

@@ -0,0 +1,18 @@
+{
+  "id": "{{PLUGIN_ID}}",
+  "name": "{{PLUGIN_NAME}}",
+  "version": "0.1.0",
+  "apiVersion": "^0.1.0",
+  "description": "{{PLUGIN_DESCRIPTION}}",
+  "author": "{{PLUGIN_AUTHOR}}",
+  "license": "{{PLUGIN_LICENSE}}",
+  "permissions": {
+    "network": [],
+    "filesystem": "plugin-data-only",
+    "llm": false,
+    "memory": false
+  },
+  "contributes": {
+    "hooks": [{ "point": "afterChat", "type": "observer" }]
+  }
+}

package/templates/hook-only/index.ts

@@ -0,0 +1,40 @@
+import { defineGrimoire, type GrimoireManifest } from "@chronicler/grimoire";
+
+export const manifest: GrimoireManifest = {
+  id: "{{PLUGIN_ID}}",
+  name: "{{PLUGIN_NAME}}",
+  version: "0.1.0",
+  apiVersion: "^0.1.0",
+  description: "{{PLUGIN_DESCRIPTION}}",
+  author: "{{PLUGIN_AUTHOR}}",
+  license: "{{PLUGIN_LICENSE}}",
+  permissions: {
+    network: [],
+    filesystem: "plugin-data-only",
+    llm: false,
+    memory: false,
+  },
+  contributes: {
+    hooks: [{ point: "afterChat", type: "observer" }],
+  },
+};
+
+export default defineGrimoire({
+  id: "{{PLUGIN_ID}}",
+
+  setup(ctx) {
+    ctx.hooks.afterChat.observe(async (event, api) => {
+      // event.reply.content is the assistant reply.
+      // event.sessionId, event.character are also available.
+      api.logger.info(
+        `${event.character.name} replied (${event.reply.content.length} chars)`
+      );
+    });
+
+    return {
+      dispose() {
+        // Clean up timers / subscriptions here if any.
+      },
+    };
+  },
+});

package/templates/hook-only/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{PLUGIN_ID}}",
+  "version": "0.1.0",
+  "description": "{{PLUGIN_DESCRIPTION}}",
+  "type": "module",
+  "main": "index.ts",
+  "author": "{{PLUGIN_AUTHOR}}",
+  "license": "{{PLUGIN_LICENSE}}",
+  "devDependencies": {
+    "@chronicler/grimoire": "^0.1.0",
+    "typescript": "~5.8.3"
+  }
+}

package/templates/slash-command/README.md

@@ -0,0 +1,26 @@
+# {{PLUGIN_NAME}}
+
+{{PLUGIN_DESCRIPTION}}
+
+A [Chronicler Grimoire](https://github.com/yantrikos/chronicler) plugin.
+
+## Install
+
+Drop into your Chronicler plugins directory:
+
+```bash
+git clone <repo-url> ~/.chronicler/plugins/{{PLUGIN_ID}}
+```
+
+Or paste the repo URL into the Browse Grimoire modal in the Chronicler UI.
+
+## Develop
+
+```bash
+npm install
+# edit index.ts
+```
+
+## License
+
+{{PLUGIN_LICENSE}}

package/templates/slash-command/grimoire.json

@@ -0,0 +1,18 @@
+{
+  "id": "{{PLUGIN_ID}}",
+  "name": "{{PLUGIN_NAME}}",
+  "version": "0.1.0",
+  "apiVersion": "^0.1.0",
+  "description": "{{PLUGIN_DESCRIPTION}}",
+  "author": "{{PLUGIN_AUTHOR}}",
+  "license": "{{PLUGIN_LICENSE}}",
+  "permissions": {
+    "network": [],
+    "filesystem": "plugin-data-only",
+    "llm": false,
+    "memory": false
+  },
+  "contributes": {
+    "commands": ["greet"]
+  }
+}

package/templates/slash-command/index.ts

@@ -0,0 +1,37 @@
+import { defineGrimoire, type GrimoireManifest } from "@chronicler/grimoire";
+
+export const manifest: GrimoireManifest = {
+  id: "{{PLUGIN_ID}}",
+  name: "{{PLUGIN_NAME}}",
+  version: "0.1.0",
+  apiVersion: "^0.1.0",
+  description: "{{PLUGIN_DESCRIPTION}}",
+  author: "{{PLUGIN_AUTHOR}}",
+  license: "{{PLUGIN_LICENSE}}",
+  permissions: {
+    network: [],
+    filesystem: "plugin-data-only",
+    llm: false,
+    memory: false,
+  },
+  contributes: {
+    commands: ["greet"],
+  },
+};
+
+export default defineGrimoire({
+  id: "{{PLUGIN_ID}}",
+
+  setup(ctx) {
+    ctx.commands.register({
+      name: "greet",
+      description: "Print a friendly greeting",
+      run: async (args, api) => {
+        const target = args.trim() || "there";
+        return { kind: "text", content: `Hello, ${target}! 👋` };
+      },
+    });
+
+    return {};
+  },
+});

package/templates/slash-command/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{PLUGIN_ID}}",
+  "version": "0.1.0",
+  "description": "{{PLUGIN_DESCRIPTION}}",
+  "type": "module",
+  "main": "index.ts",
+  "author": "{{PLUGIN_AUTHOR}}",
+  "license": "{{PLUGIN_LICENSE}}",
+  "devDependencies": {
+    "@chronicler/grimoire": "^0.1.0",
+    "typescript": "~5.8.3"
+  }
+}

package/templates/ui-slot/Panel.tsx

@@ -0,0 +1,25 @@
+interface Props {
+  pluginId: string;
+  characterId: string | null;
+}
+
+export function Panel({ pluginId, characterId }: Props) {
+  return (
+    <div className="h-full overflow-y-auto p-4 text-xs text-neutral-300">
+      <header className="mb-3">
+        <h2 className="text-sm font-semibold text-neutral-100 mb-0.5">
+          {{PLUGIN_NAME}}
+        </h2>
+        <p className="text-[11px] text-neutral-500">
+          Plugin <code className="text-emerald-400">{pluginId}</code>{" "}
+          {characterId && (
+            <>· active: <code className="text-neutral-200">{characterId}</code></>
+          )}
+        </p>
+      </header>
+      <p className="text-neutral-400 leading-relaxed">
+        Edit <code>Panel.tsx</code> to make this panel useful.
+      </p>
+    </div>
+  );
+}

package/templates/ui-slot/README.md

@@ -0,0 +1,26 @@
+# {{PLUGIN_NAME}}
+
+{{PLUGIN_DESCRIPTION}}
+
+A [Chronicler Grimoire](https://github.com/yantrikos/chronicler) plugin.
+
+## Install
+
+Drop into your Chronicler plugins directory:
+
+```bash
+git clone <repo-url> ~/.chronicler/plugins/{{PLUGIN_ID}}
+```
+
+Or paste the repo URL into the Browse Grimoire modal in the Chronicler UI.
+
+## Develop
+
+```bash
+npm install
+# edit index.ts
+```
+
+## License
+
+{{PLUGIN_LICENSE}}

package/templates/ui-slot/grimoire.json

@@ -0,0 +1,18 @@
+{
+  "id": "{{PLUGIN_ID}}",
+  "name": "{{PLUGIN_NAME}}",
+  "version": "0.1.0",
+  "apiVersion": "^0.1.0",
+  "description": "{{PLUGIN_DESCRIPTION}}",
+  "author": "{{PLUGIN_AUTHOR}}",
+  "license": "{{PLUGIN_LICENSE}}",
+  "permissions": {
+    "network": [],
+    "filesystem": "plugin-data-only",
+    "llm": false,
+    "memory": false
+  },
+  "contributes": {
+    "ui": { "slots": ["inspector:tab"] }
+  }
+}

package/templates/ui-slot/index.ts

@@ -0,0 +1,32 @@
+import { defineGrimoire, type GrimoireManifest } from "@chronicler/grimoire";
+import { Panel } from "./Panel";
+
+export const manifest: GrimoireManifest = {
+  id: "{{PLUGIN_ID}}",
+  name: "{{PLUGIN_NAME}}",
+  version: "0.1.0",
+  apiVersion: "^0.1.0",
+  description: "{{PLUGIN_DESCRIPTION}}",
+  author: "{{PLUGIN_AUTHOR}}",
+  license: "{{PLUGIN_LICENSE}}",
+  permissions: {
+    network: [],
+    filesystem: "plugin-data-only",
+    llm: false,
+    memory: false,
+  },
+  contributes: {
+    ui: { slots: ["inspector:tab"] },
+  },
+};
+
+export default defineGrimoire({
+  id: "{{PLUGIN_ID}}",
+
+  setup(ctx) {
+    ctx.ui.registerSlot("inspector:tab", Panel, {
+      title: "{{PLUGIN_NAME}}",
+    });
+    return {};
+  },
+});

package/templates/ui-slot/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{PLUGIN_ID}}",
+  "version": "0.1.0",
+  "description": "{{PLUGIN_DESCRIPTION}}",
+  "type": "module",
+  "main": "index.ts",
+  "author": "{{PLUGIN_AUTHOR}}",
+  "license": "{{PLUGIN_LICENSE}}",
+  "devDependencies": {
+    "@chronicler/grimoire": "^0.1.0",
+    "typescript": "~5.8.3"
+  }
+}