create-agntcms-app 0.2.1

package/README.md

@@ -0,0 +1,39 @@
+# create-agntcms-app
+
+Scaffold a new agntcms project from the canonical template.
+
+## Usage
+
+```bash
+npx create-agntcms-app my-site
+cd my-site
+pnpm dev
+```
+
+## Local development (monorepo)
+
+When developing the framework itself, use `--local` to link the scaffolded
+project back to your monorepo checkout via `file:` protocol:
+
+```bash
+# 1. Build all packages
+pnpm build
+
+# 2. Scaffold with --local
+node packages/cli/dist/index.mjs --local ~/test-site
+
+# 3. Start watch mode in the monorepo (rebuilds packages on change)
+pnpm dev
+
+# 4. Start the scaffolded project
+cd ~/test-site && pnpm dev
+```
+
+Changes in `packages/next/` are rebuilt by the monorepo watcher and picked up
+automatically by the scaffolded project through the symlink.
+
+### What `--local` does
+
+- Rewrites `workspace:*` dependencies to `file:` references pointing at the monorepo
+- Points `tsconfig.json` extends at the monorepo's `tsconfig.base.json`
+- Everything else (template copy, skills init, Telegram setup) works identically

package/dist/index.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import * as readline from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+
+// src/scaffold.ts
+import * as fs from "fs";
+import * as path2 from "path";
+import { execSync as execSync2 } from "child_process";
+import { syncSkills } from "@agntcms/skills";
+
+// src/utils.ts
+import { existsSync } from "fs";
+import { execSync } from "child_process";
+import * as path from "path";
+function detectPackageManager() {
+  const cwd = process.cwd();
+  if (existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(path.join(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync(path.join(cwd, "package-lock.json"))) return "npm";
+  if (commandExists("pnpm")) return "pnpm";
+  if (commandExists("yarn")) return "yarn";
+  return "npm";
+}
+function commandExists(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function installCommand(pm) {
+  switch (pm) {
+    case "pnpm":
+      return "pnpm install";
+    case "yarn":
+      return "yarn install";
+    case "npm":
+      return "npm install";
+  }
+}
+
+// src/version.ts
+var CLI_VERSION = true ? "0.2.1" : "0.0.0-dev";
+
+// src/scaffold.ts
+var COPY_EXCLUDES = /* @__PURE__ */ new Set([
+  ".next",
+  ".turbo",
+  "node_modules",
+  "tsconfig.tsbuildinfo",
+  "next-env.d.ts"
+  // next generates this on first dev run
+]);
+var WORKSPACE_PACKAGE_VERSION_MAP = {
+  "@agntcms/next": CLI_VERSION,
+  "@agntcms/skills": CLI_VERSION
+};
+async function scaffold(targetDir, options = {}) {
+  const absoluteTarget = path2.resolve(targetDir);
+  const projectName = path2.basename(absoluteTarget);
+  const local = options.local ?? false;
+  validateTarget(absoluteTarget);
+  const templateDir = resolveTemplateDir();
+  const monorepoRoot = local ? resolveMonorepoRoot() : void 0;
+  console.log(`
+Scaffolding agntcms project into ${absoluteTarget} ...
+`);
+  copyTemplate(templateDir, absoluteTarget);
+  rewritePackageJson(absoluteTarget, projectName, { local, monorepoRoot });
+  rewriteTsconfig(absoluteTarget, { local, monorepoRoot });
+  if (local && monorepoRoot !== void 0) {
+    console.log(`Building monorepo packages for --local mode (${monorepoRoot}) ...
+`);
+    execSync2("pnpm build", { cwd: monorepoRoot, stdio: "inherit" });
+  }
+  const pm = detectPackageManager();
+  console.log(`Installing dependencies with ${pm} ...
+`);
+  execSync2(installCommand(pm), { cwd: absoluteTarget, stdio: "inherit" });
+  console.log("Initializing .claude/skills/ ...\n");
+  await syncSkills(absoluteTarget);
+  const gitkeep = path2.join(absoluteTarget, ".claude", "skills", ".gitkeep");
+  if (fs.existsSync(gitkeep)) {
+    fs.rmSync(gitkeep);
+  }
+  printNextSteps(projectName, pm, { local, monorepoRoot });
+}
+function validateTarget(absoluteTarget) {
+  if (!fs.existsSync(absoluteTarget)) {
+    return;
+  }
+  const stat = fs.statSync(absoluteTarget);
+  if (!stat.isDirectory()) {
+    throw new Error(`${absoluteTarget} already exists and is not a directory.`);
+  }
+  const entries = fs.readdirSync(absoluteTarget).filter((e) => e !== ".git");
+  if (entries.length > 0) {
+    throw new Error(
+      `Directory ${absoluteTarget} already exists and is not empty. Please choose an empty directory or a new path.`
+    );
+  }
+}
+function resolveTemplateDir() {
+  const here = path2.dirname(new URL(import.meta.url).pathname);
+  const candidates = [
+    path2.resolve(here, "template"),
+    path2.resolve(here, "..", "template"),
+    path2.resolve(here, "..", "..", "..", "template")
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `Cannot locate template directory. Searched:
+` + candidates.map((c) => `  ${c}`).join("\n")
+  );
+}
+function resolveMonorepoRoot() {
+  const here = path2.dirname(new URL(import.meta.url).pathname);
+  const candidate = path2.resolve(here, "..", "..", "..");
+  const marker = path2.join(candidate, "packages", "next", "package.json");
+  if (fs.existsSync(marker)) {
+    return candidate;
+  }
+  throw new Error(
+    `Cannot find monorepo root. --local only works when running from the agntcms source tree.
+Looked for: ${marker}`
+  );
+}
+function copyTemplate(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  copyDir(src, dest);
+}
+function copyDir(src, dest) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (COPY_EXCLUDES.has(entry.name)) continue;
+    const srcPath = path2.join(src, entry.name);
+    const destPath = path2.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+function rewritePackageJson(projectDir, projectName, opts) {
+  const pkgPath = path2.join(projectDir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    return;
+  }
+  const raw = fs.readFileSync(pkgPath, "utf-8");
+  const pkg = JSON.parse(raw);
+  if (!isRecord(pkg)) {
+    throw new Error(`package.json in template is not a JSON object.`);
+  }
+  pkg["name"] = projectName;
+  delete pkg["private"];
+  rewriteWorkspaceDeps(pkg, "dependencies", opts);
+  rewriteWorkspaceDeps(pkg, "devDependencies", opts);
+  rewriteWorkspaceDeps(pkg, "peerDependencies", opts);
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+}
+var WORKSPACE_PACKAGE_DIR_MAP = {
+  "@agntcms/next": "packages/next",
+  "@agntcms/skills": "packages/skills"
+};
+function rewriteWorkspaceDeps(pkg, field, opts) {
+  const deps = pkg[field];
+  if (!isRecord(deps)) return;
+  for (const [name, version] of Object.entries(deps)) {
+    if (typeof version === "string" && version.startsWith("workspace:")) {
+      if (opts.local && opts.monorepoRoot !== void 0) {
+        const subdir = WORKSPACE_PACKAGE_DIR_MAP[name];
+        if (subdir !== void 0) {
+          deps[name] = `file:${path2.join(opts.monorepoRoot, subdir)}`;
+          continue;
+        }
+      }
+      const mapped = WORKSPACE_PACKAGE_VERSION_MAP[name];
+      deps[name] = mapped !== void 0 ? `^${mapped}` : `^${CLI_VERSION}`;
+    }
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rewriteTsconfig(projectDir, opts) {
+  const tsconfigPath = path2.join(projectDir, "tsconfig.json");
+  if (!fs.existsSync(tsconfigPath)) {
+    return;
+  }
+  const raw = fs.readFileSync(tsconfigPath, "utf-8");
+  const tsconfig = JSON.parse(raw);
+  if (!isRecord(tsconfig)) return;
+  const extendsValue = tsconfig["extends"];
+  if (typeof extendsValue !== "string" || !extendsValue.includes("tsconfig.base")) {
+    return;
+  }
+  if (opts.local && opts.monorepoRoot !== void 0) {
+    tsconfig["extends"] = path2.join(opts.monorepoRoot, "tsconfig.base.json");
+    fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n", "utf-8");
+    return;
+  }
+  delete tsconfig["extends"];
+  const base = {
+    target: "ES2022",
+    lib: ["ES2022", "DOM", "DOM.Iterable"],
+    module: "ESNext",
+    moduleResolution: "Bundler",
+    resolveJsonModule: true,
+    isolatedModules: true,
+    verbatimModuleSyntax: true,
+    esModuleInterop: true,
+    forceConsistentCasingInFileNames: true,
+    skipLibCheck: true,
+    strict: true,
+    noUncheckedIndexedAccess: true,
+    noImplicitOverride: true,
+    noFallthroughCasesInSwitch: true,
+    exactOptionalPropertyTypes: true,
+    declaration: true,
+    declarationMap: true,
+    sourceMap: true,
+    useDefineForClassFields: true
+  };
+  const existing = isRecord(tsconfig["compilerOptions"]) ? tsconfig["compilerOptions"] : {};
+  tsconfig["compilerOptions"] = { ...base, ...existing };
+  fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n", "utf-8");
+}
+function printNextSteps(projectName, pm, opts) {
+  const runCmd = pm === "npm" ? "npm run" : pm;
+  const localNote = opts.local && opts.monorepoRoot !== void 0 ? `
+  Warning: Local mode: dependencies are symlinked to the monorepo at ${opts.monorepoRoot}.
+    Run "pnpm dev" in the monorepo to keep packages rebuilt in watch mode.
+` : "";
+  console.log(`
+agntcms project created successfully!
+${localNote}
+Next steps:
+
+First, personalize the template:
+
+  cd ${projectName}
+  claude                         # open Claude Code in the project
+  /agntcms-init                 # interview-driven personalization (or "explore demo" branch)
+
+Or skip the interview and run \`${runCmd} dev\` to explore the agntcms demo as-is.
+
+  ${runCmd} dev            # start the dev server at http://localhost:3000
+
+  ${runCmd} build          # production build
+
+To configure your project:
+  - Edit agntcms/config.ts to register sections and adapters.
+  - Add new sections under agntcms/sections/<SectionName>/.
+  - Run \`pnpm dev\` alongside an interactive Claude Code session to enable agent-driven editing.
+`);
+}
+
+// src/index.ts
+var program = new Command();
+program.name("create-agntcms-app").description("Scaffold a new agntcms project from the canonical template").version(CLI_VERSION).argument("[dir]", "Target directory for the new project").option(
+  "--local",
+  "Link to local monorepo packages via file: protocol (dev only)"
+).action(async (dir, opts) => {
+  let targetDir = dir?.trim();
+  if (!targetDir) {
+    const rl = readline.createInterface({ input, output });
+    try {
+      targetDir = (await rl.question("Project directory name: ")).trim();
+    } finally {
+      rl.close();
+    }
+  }
+  if (!targetDir) {
+    console.error("Error: a target directory is required.");
+    process.exit(1);
+  }
+  try {
+    await scaffold(targetDir, { local: opts.local ?? false });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`
+Error: ${message}
+`);
+    process.exit(1);
+  }
+});
+program.parse();

package/dist/template/.claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "mcpServers": {},
+  "enabledPlugins": {
+    "frontend-design@claude-plugins-official": true
+  }
+}

package/dist/template/.claude-plugin/channel/server.mjs

@@ -0,0 +1,254 @@
+// server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import * as http from "http";
+var CHANNEL_PORT = Number(process.env["agntcms_CHANNEL_PORT"] ?? 4819);
+var DEFAULT_CALLBACK_URL = process.env["agntcms_CALLBACK_URL"] ?? "http://localhost:3000/api/agntcms/mcp";
+var taskCallbacks = /* @__PURE__ */ new Map();
+var INSTRUCTIONS = [
+  "Tasks from the agntcms runtime arrive as channel messages.",
+  'Each message starts with "task_assigned" followed by task_id, type, and payload fields.',
+  "",
+  "For every task_assigned message:",
+  "1. Parse the task_id, type, and payload.",
+  "2. Check your loaded skills for one that covers this task type",
+  "   (e.g. agntcms-section-replace for type=section_replace).",
+  "   If a skill matches, follow its workflow.",
+  "3. Carry out the work using your file tools.",
+  "4. Report completion by calling the report_task_done tool with the",
+  "   exact task_id and a short human-readable result.",
+  "5. For long-running tasks, call report_task_progress one or more times",
+  "   before report_task_done.",
+  "",
+  "Always call report_task_done, even on error \u2014 use a result starting",
+  'with "Error: " and a short reason. Never leave a task without a',
+  "report_task_done call.",
+  "",
+  "IMPORTANT: Never read image files (png, jpg, jpeg, gif, webp, svg, ico).",
+  "Image paths in content JSON are opaque strings \u2014 copy them as-is.",
+  "You only edit text: JSON content files, TypeScript config, Markdown."
+].join("\n");
+var mcp = new Server(
+  { name: "agntcms", version: "0.1.6" },
+  {
+    capabilities: {
+      tools: {},
+      experimental: {
+        "claude/channel": {}
+      }
+    },
+    instructions: INSTRUCTIONS
+  }
+);
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "report_task_done",
+      description: "Report that an assigned task has been completed. Pass the task_id from the task_assigned message and a short human-readable result.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_id: {
+            type: "string",
+            description: "The task_id from the task_assigned message"
+          },
+          result: {
+            type: "string",
+            description: "Short human-readable description of what was done"
+          }
+        },
+        required: ["task_id", "result"]
+      }
+    },
+    {
+      name: "report_task_progress",
+      description: "Report incremental progress on a long-running task. Optional \u2014 only use for tasks that take more than a few seconds.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_id: {
+            type: "string",
+            description: "The task_id from the task_assigned message"
+          },
+          message: {
+            type: "string",
+            description: "Short progress update"
+          }
+        },
+        required: ["task_id", "message"]
+      }
+    }
+  ]
+}));
+var postCallback = async (callbackUrl, body) => {
+  const res = await fetch(callbackUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    throw new Error(`callback returned ${String(res.status)}`);
+  }
+};
+mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name } = request.params;
+  const args = request.params.arguments ?? {};
+  switch (name) {
+    case "report_task_done": {
+      const taskId = String(args["task_id"] ?? "");
+      const result = String(args["result"] ?? "");
+      const callbackUrl = taskCallbacks.get(taskId) ?? DEFAULT_CALLBACK_URL;
+      try {
+        await postCallback(callbackUrl, {
+          action: "task_callback",
+          event: "completed",
+          task_id: taskId,
+          result
+        });
+        taskCallbacks.delete(taskId);
+        return { content: [{ type: "text", text: `acknowledged: ${taskId}` }] };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `callback failed: ${msg}` }],
+          isError: true
+        };
+      }
+    }
+    case "report_task_progress": {
+      const taskId = String(args["task_id"] ?? "");
+      const message = String(args["message"] ?? "");
+      const callbackUrl = taskCallbacks.get(taskId) ?? DEFAULT_CALLBACK_URL;
+      try {
+        await postCallback(callbackUrl, {
+          action: "task_callback",
+          event: "progress",
+          task_id: taskId,
+          message
+        });
+        return { content: [{ type: "text", text: `progress recorded for ${taskId}` }] };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `callback failed: ${msg}` }],
+          isError: true
+        };
+      }
+    }
+    default:
+      return {
+        content: [{ type: "text", text: `unknown tool: ${name}` }],
+        isError: true
+      };
+  }
+});
+var buildTaskAssignedText = (taskId, type, payload) => {
+  const payloadJson = (() => {
+    try {
+      return JSON.stringify(payload);
+    } catch {
+      return '"<unserializable payload>"';
+    }
+  })();
+  return [
+    "task_assigned",
+    `task_id=${taskId}`,
+    `type=${type}`,
+    `payload=${payloadJson}`,
+    "",
+    "Carry out the task and then call report_task_done with the task_id above."
+  ].join("\n");
+};
+var readBody = async (req) => {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+};
+var jsonResponse = (res, status, body) => {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+};
+var httpServer = http.createServer((req, res) => {
+  if (req.method === "GET" && req.url === "/health") {
+    jsonResponse(res, 200, { status: "ok" });
+    return;
+  }
+  if (req.method === "POST" && req.url === "/task") {
+    readBody(req).then((raw) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        jsonResponse(res, 400, { error: "invalid_json" });
+        return;
+      }
+      const taskId = parsed["task_id"];
+      const type = parsed["type"];
+      const payload = parsed["payload"];
+      const callbackUrl = parsed["callback_url"];
+      if (typeof taskId !== "string" || taskId === "") {
+        jsonResponse(res, 400, {
+          error: "missing_field",
+          message: "task_id is required"
+        });
+        return;
+      }
+      if (typeof type !== "string" || type === "") {
+        jsonResponse(res, 400, {
+          error: "missing_field",
+          message: "type is required"
+        });
+        return;
+      }
+      const resolvedCallback = typeof callbackUrl === "string" && callbackUrl !== "" ? callbackUrl : DEFAULT_CALLBACK_URL;
+      taskCallbacks.set(taskId, resolvedCallback);
+      const content = buildTaskAssignedText(taskId, type, payload);
+      mcp.notification({
+        method: "notifications/claude/channel",
+        params: { content, meta: { task_id: taskId, type } }
+      }).then(() => {
+        jsonResponse(res, 200, { ok: true, task_id: taskId });
+      }).catch((err) => {
+        taskCallbacks.delete(taskId);
+        const msg = err instanceof Error ? err.message : String(err);
+        jsonResponse(res, 502, {
+          error: "notification_failed",
+          message: msg
+        });
+      });
+    }).catch(() => {
+      jsonResponse(res, 500, { error: "internal" });
+    });
+    return;
+  }
+  jsonResponse(res, 404, { error: "not_found" });
+});
+var isDirectRun = process.argv[1] !== void 0 && (process.argv[1].endsWith("/server.mjs") || process.argv[1].endsWith("/server.js") || process.argv[1].endsWith("/server.ts"));
+if (isDirectRun) {
+  const transport = new StdioServerTransport();
+  mcp.connect(transport).then(() => {
+    httpServer.listen(CHANNEL_PORT, "127.0.0.1", () => {
+      process.stderr.write(
+        `agntcms channel server listening on 127.0.0.1:${String(CHANNEL_PORT)}
+`
+      );
+    });
+  }).catch((err) => {
+    process.stderr.write(`agntcms channel server fatal: ${String(err)}
+`);
+    process.exit(1);
+  });
+}
+export {
+  INSTRUCTIONS,
+  buildTaskAssignedText,
+  httpServer,
+  mcp,
+  taskCallbacks
+};