@k0t0vich/meta-agents-template 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.1.7 - 2026-03-20
+
+### Changed
+- Switched `meta-agents init` to non-destructive bootstrap: root now gets only `.meta-agents/config/*`, while automation rules are consumed from `node_modules/@k0t0vich/meta-agents-template`.
+- Prevented accidental overwrite of existing project `agents.md`: init now appends/updates only a managed links block instead of replacing full content.
+- Reworked package setup in existing projects: `package.json` is merged (not replaced), preserving existing scripts while adding `meta:*` commands and `devDependencies` entry.
+- Added runtime package self-install during init when package files are not present locally (safe `npx` path).
+- Updated public README with robust one-line onboarding for npm URL/package-name prompts and new post-init layout.
+- Updated local post-publish smoke to validate the new config-only root flow.
+
 ## 0.1.6 - 2026-03-20
 
 ### Changed

package/README.md

@@ -9,17 +9,46 @@
 - командный протокол работы с задачами и спринтами;
 - выбор backend-трекера (`github`, `mcp`, `local`, `custom`).
 
-## Установка
+## Установка (надёжно из любой папки)
+Если целевая папка пустая или в ней нет `package.json`, сначала зафиксируй локальный npm-проект:
+
 ```bash
+mkdir -p my-project
+cd my-project
+npm init -y
 npm i -D @k0t0vich/meta-agents-template
-npx meta-agents init my-project
+npx meta-agents init . --yes --tracker github
+```
+
+Альтернатива через `npx` (init сам добавит пакет в `devDependencies`, если его нет локально):
+
+```bash
+mkdir -p my-project
+cd my-project
+npx -y @k0t0vich/meta-agents-template init . --yes --tracker github
+```
+
+Важно:
+- если пользователь дал URL `https://www.npmjs.com/package/@k0t0vich/meta-agents-template`, извлекай имя пакета `@k0t0vich/meta-agents-template` и ставь именно его;
+- не запускай `npm i -D ...` в папке без `package.json`, иначе npm может установить пакет в родительский проект.
+- `meta-agents init` по умолчанию работает non-destructive: в корне создаёт/обновляет только `.meta-agents/config/*`, аккуратно merge-ит `meta:*` scripts в `package.json` и добавляет ссылочный блок в `agents.md` вместо полной перезаписи.
+- `--force` нужен только если надо перезаписать уже существующие `.meta-agents/config/*` и мигрировать legacy `meta:*` scripts.
+
+## One-line для агентного запуска
+Если пользователь пишет только:
+- `поставь https://www.npmjs.com/package/@k0t0vich/meta-agents-template`
+- `поставь @k0t0vich/meta-agents-template`
+
+используй безопасный one-liner:
+
+```bash
+mkdir -p my-project && cd my-project && npm init -y && npm i -D @k0t0vich/meta-agents-template && npx meta-agents init . --yes --tracker github
 ```
 
-или
+Проверка, что шаблон и правила действительно развернуты:
 
 ```bash
-npm i -D git+https://github.com/k0t0vich/meta-agents-template.git
-npx meta-agents init my-project
+test -f agents.md && test -f .meta-agents/config/project-context.yaml && test -f node_modules/@k0t0vich/meta-agents-template/agents.md && echo "meta-agents template ready"
 ```
 
 ## Диалог при `init`
@@ -33,55 +62,24 @@ npx meta-agents init my-project
 ## Структура проекта после `init`
 ```text
 my-project/
-  .github/
-    workflows/
-      gitflow-lite-verify.yml
   package.json
-  README.md
+  package-lock.json
   agents.md
-  tracker-command-template.md
   .meta-agents/
     config/
       system.yaml
       roles.yaml
       trackers.yaml
       project-context.yaml
-    templates/
-      prd-step.md
-      agent-work-contract.md
-      verification-plan.md
-      evidence-pack.md
-      sprint-template.md
-      task-template.md
-    prompts/
-      clarifier.md
-      architect.md
-      verifier-designer.md
-      decomposer.md
-      reviewer-judge.md
-      mr-review-agent.md
-      agile-manager.md
-      publishing-agent.md
-      status-agent.md
-    scripts/
-      init.mjs
-      sync-status.mjs
-      verify-branch-strategy.mjs
-      task-branch-router.mjs
-      run-mr-review-gate.mjs
-      generate-prd-step.mjs
-      tracker/
-        local.mjs
-        github.mjs
-        mcp.mjs
-        custom.mjs
-      tracker-gateway.mjs
-  tasks/
-    backlog.md
-    sprint-1.md
-    task-status-log.md
+  node_modules/
+    @k0t0vich/meta-agents-template/
+      agents.md
+      tracker-command-template.md
+      template/.meta-agents/scripts/*.mjs
 ```
 
+`agents.md` в проекте не перезаписывается целиком: `init` добавляет/обновляет в нём только ссылочный блок на правила из npm-пакета.
+
 ## Канонические команды
 0. `VERIFY_GOVERNANCE_GATE`
 1. `CREATE_TASK`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k0t0vich/meta-agents-template",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Template system for verification-first agentic development",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import readline from "node:readline/promises";
@@ -8,6 +9,25 @@ import { syncTemplate } from "./sync.mjs";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const templateRoot = path.resolve(__dirname, "..", "template");
+const packageManifestPath = path.resolve(__dirname, "..", "package.json");
+
+function readSelfPackageIdentity() {
+  try {
+    const raw = fs.readFileSync(packageManifestPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      name: String(parsed.name || "@k0t0vich/meta-agents-template"),
+      version: String(parsed.version || ""),
+    };
+  } catch {
+    return {
+      name: "@k0t0vich/meta-agents-template",
+      version: "",
+    };
+  }
+}
+
+const selfPackage = readSelfPackageIdentity();
 
 function parseOptions(args) {
   const options = {
@@ -60,13 +80,14 @@ function printHelp() {
     "  meta-agents --help",
     "",
     "Commands:",
-    "  init     Initialize a project from template",
+    "  init     Initialize a project (config-only in root, npm-linked rules)",
     "  sync     Update managed template files in an existing project",
     "  upgrade  Alias for sync",
     "",
     "Init dialog:",
     "  By default, 'init' asks about Git mode and tracker provider.",
     "  Use --yes to skip dialog and use defaults/flags.",
+    "  --force overwrites existing .meta-agents/config files and updates legacy meta:* scripts.",
   ];
   console.log(lines.join("\n"));
 }
@@ -233,11 +254,38 @@ export async function main(argv) {
       tracker,
       force: options.force,
       gitSetup,
+      packageName: selfPackage.name,
+      packageVersion: selfPackage.version,
     });
 
     console.log(`Initialized meta-agents project at: ${result.targetDir}`);
     console.log(`Default tracker: ${tracker}`);
     console.log(`Git mode: ${result.git.mode}`);
+    if (result.packageJson.created) {
+      console.log("Package manifest: created package.json");
+    }
+    if (result.packageJson.dependencyAdded) {
+      console.log(`Package dependency: added ${selfPackage.name} to devDependencies`);
+    }
+    if (result.packageJson.updatedScripts.length > 0) {
+      console.log(`Meta scripts updated: ${result.packageJson.updatedScripts.join(", ")}`);
+    }
+    if (result.runtimePackage.installedNow) {
+      console.log(`Runtime package installed: ${selfPackage.name}`);
+    }
+    if (result.config.updated.length > 0) {
+      console.log(`Config files written: ${result.config.updated.join(", ")}`);
+    }
+    if (result.config.skipped.length > 0) {
+      console.log(`Config files kept: ${result.config.skipped.join(", ")}`);
+    }
+    if (result.agents.created) {
+      console.log("agents.md: created with npm links to template rules");
+    } else if (result.agents.updated) {
+      console.log("agents.md: appended/updated npm links block");
+    } else {
+      console.log("agents.md: npm links block already up to date");
+    }
     if (result.git.actions.length > 0) {
       console.log(`Git actions: ${result.git.actions.join("; ")}`);
     }

package/src/init.mjs

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
+import process from "node:process";
 
 const TEXT_EXTENSIONS = new Set([
   ".md",
@@ -12,10 +13,25 @@ const TEXT_EXTENSIONS = new Set([
   ".js",
 ]);
 
+const AGENTS_LINK_BLOCK_START = "<!-- meta-agents-template:links:start -->";
+const AGENTS_LINK_BLOCK_END = "<!-- meta-agents-template:links:end -->";
+
 function resolveTargetDir(cwd, target) {
   return path.resolve(cwd, target);
 }
 
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function replaceTemplatePlaceholders(input, values) {
+  let output = input;
+  for (const [key, value] of Object.entries(values)) {
+    output = output.replaceAll(`__${key}__`, value);
+  }
+  return output;
+}
+
 async function runCommand(command, args, cwd, allowFailure = false) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
@@ -51,6 +67,15 @@ async function runCommand(command, args, cwd, allowFailure = false) {
   });
 }
 
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function directoryExists(dir) {
   try {
     const stat = await fs.stat(dir);
@@ -60,11 +85,6 @@ async function directoryExists(dir) {
   }
 }
 
-async function isDirectoryEmpty(dir) {
-  const entries = await fs.readdir(dir);
-  return entries.length === 0;
-}
-
 async function walkFiles(dir, list = []) {
   const entries = await fs.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
@@ -82,25 +102,198 @@ function shouldReplacePlaceholders(filePath) {
   return TEXT_EXTENSIONS.has(path.extname(filePath));
 }
 
-async function replacePlaceholders(rootDir, values) {
-  const files = await walkFiles(rootDir);
+function buildMetaScripts(packageName) {
+  const base = `node ./node_modules/${packageName}/template/.meta-agents/scripts`;
+  return {
+    "meta:status": `${base}/sync-status.mjs`,
+    "meta:branch": `${base}/verify-branch-strategy.mjs`,
+    "meta:task-start": `${base}/task-branch-router.mjs`,
+    "meta:verify": `${base}/verify-governance.mjs`,
+    "meta:review": `${base}/run-review-gate.mjs`,
+    "meta:review-approve": `${base}/run-review-gate.mjs --approve yes`,
+    "meta:mr-review": `${base}/run-mr-review-gate.mjs`,
+    "meta:mr-review-approve": `${base}/run-mr-review-gate.mjs --approve yes`,
+    "meta:verify-link": `${base}/verify-commit-link.mjs`,
+    "meta:ops": `${base}/tracker-gateway.mjs`,
+  };
+}
+
+function isLegacyMetaScript(value) {
+  return (
+    value.includes(".meta-agents/scripts/") ||
+    value.includes("meta-agents-template/template/.meta-agents/scripts/")
+  );
+}
+
+function defaultPackageNameFromDir(targetDir) {
+  const raw = path.basename(targetDir).toLowerCase();
+  const sanitized = raw.replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return sanitized || "meta-agents-project";
+}
+
+async function ensurePackageJson(targetDir) {
+  const packageJsonPath = path.join(targetDir, "package.json");
+  if (await pathExists(packageJsonPath)) {
+    const input = await fs.readFile(packageJsonPath, "utf8");
+    try {
+      return {
+        path: packageJsonPath,
+        data: JSON.parse(input),
+        created: false,
+      };
+    } catch (error) {
+      throw new Error(`invalid package.json at ${packageJsonPath}: ${error.message}`);
+    }
+  }
+
+  const data = {
+    name: defaultPackageNameFromDir(targetDir),
+    version: "0.1.0",
+    private: true,
+    scripts: {},
+    devDependencies: {},
+  };
+  return {
+    path: packageJsonPath,
+    data,
+    created: true,
+  };
+}
+
+async function mergePackageJsonMeta({
+  targetDir,
+  packageName,
+  packageVersion,
+  force,
+}) {
+  const packageJson = await ensurePackageJson(targetDir);
+  const data = packageJson.data || {};
+  data.scripts = data.scripts && typeof data.scripts === "object" ? data.scripts : {};
+  data.devDependencies =
+    data.devDependencies && typeof data.devDependencies === "object" ? data.devDependencies : {};
+
+  const desiredScripts = buildMetaScripts(packageName);
+  const updatedScripts = [];
+  const skippedScripts = [];
 
-  for (const file of files) {
-    if (!shouldReplacePlaceholders(file)) {
+  for (const [key, value] of Object.entries(desiredScripts)) {
+    const current = data.scripts[key];
+    if (!current) {
+      data.scripts[key] = value;
+      updatedScripts.push(key);
       continue;
     }
 
-    const input = await fs.readFile(file, "utf8");
-    let output = input;
+    if (current !== value && (force || isLegacyMetaScript(current))) {
+      data.scripts[key] = value;
+      updatedScripts.push(key);
+      continue;
+    }
+
+    skippedScripts.push(key);
+  }
+
+  let dependencyAdded = false;
+  if (!data.devDependencies[packageName]) {
+    const spec = packageVersion ? `^${packageVersion}` : "latest";
+    data.devDependencies[packageName] = spec;
+    dependencyAdded = true;
+  }
+
+  if (packageJson.created || updatedScripts.length > 0 || dependencyAdded) {
+    await fs.writeFile(packageJson.path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  }
 
-    for (const [key, value] of Object.entries(values)) {
-      output = output.replaceAll(`__${key}__`, value);
+  return {
+    created: packageJson.created,
+    updatedScripts,
+    skippedScripts,
+    dependencyAdded,
+    packageJsonPath: packageJson.path,
+  };
+}
+
+function buildAgentsLinkBlock(packageName) {
+  const packageRoot = `./node_modules/${packageName}`;
+  const lines = [
+    AGENTS_LINK_BLOCK_START,
+    "## Meta Agents Template (npm-linked)",
+    "Базовые правила шаблона:",
+    `- [Template agents.md](${packageRoot}/agents.md)`,
+    `- [Template tracker-command-template.md](${packageRoot}/tracker-command-template.md)`,
+    "Локальные конфиги проекта:",
+    "- [.meta-agents/config/project-context.yaml](./.meta-agents/config/project-context.yaml)",
+    "- [.meta-agents/config/trackers.yaml](./.meta-agents/config/trackers.yaml)",
+    "- [.meta-agents/config/system.yaml](./.meta-agents/config/system.yaml)",
+    AGENTS_LINK_BLOCK_END,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+async function upsertAgentsLinks(targetDir, packageName) {
+  const agentsPath = path.join(targetDir, "agents.md");
+  const block = buildAgentsLinkBlock(packageName);
+
+  if (!(await pathExists(agentsPath))) {
+    const content = ["# agents.md", "", block].join("\n");
+    await fs.writeFile(agentsPath, content, "utf8");
+    return { created: true, updated: false, path: agentsPath };
+  }
+
+  const input = await fs.readFile(agentsPath, "utf8");
+  const blockRegex = new RegExp(
+    `${escapeRegExp(AGENTS_LINK_BLOCK_START)}[\\s\\S]*?${escapeRegExp(AGENTS_LINK_BLOCK_END)}\\n?`,
+    "m",
+  );
+
+  let output = input;
+  let updated = false;
+
+  if (blockRegex.test(input)) {
+    output = input.replace(blockRegex, block);
+    updated = output !== input;
+  } else {
+    const glue = input.endsWith("\n") ? "\n" : "\n\n";
+    output = `${input}${glue}${block}`;
+    updated = true;
+  }
+
+  if (updated) {
+    await fs.writeFile(agentsPath, output, "utf8");
+  }
+
+  return { created: false, updated, path: agentsPath };
+}
+
+async function syncConfigFiles({ templateRoot, targetDir, values, force }) {
+  const sourceConfigRoot = path.join(templateRoot, ".meta-agents", "config");
+  const targetConfigRoot = path.join(targetDir, ".meta-agents", "config");
+  const sourceFiles = await walkFiles(sourceConfigRoot);
+
+  const updated = [];
+  const skipped = [];
+
+  for (const sourceFile of sourceFiles) {
+    const relative = path.relative(sourceConfigRoot, sourceFile);
+    const destination = path.join(targetConfigRoot, relative);
+
+    if (!force && (await pathExists(destination))) {
+      skipped.push(path.join(".meta-agents", "config", relative));
+      continue;
     }
 
-    if (output !== input) {
-      await fs.writeFile(file, output, "utf8");
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    if (shouldReplacePlaceholders(sourceFile)) {
+      const raw = await fs.readFile(sourceFile, "utf8");
+      const rendered = replaceTemplatePlaceholders(raw, values);
+      await fs.writeFile(destination, rendered, "utf8");
+    } else {
+      await fs.copyFile(sourceFile, destination);
     }
+    updated.push(path.join(".meta-agents", "config", relative));
   }
+
+  return { updated, skipped };
 }
 
 async function setupGit(targetDir, gitSetup) {
@@ -167,31 +360,70 @@ async function setupGit(targetDir, gitSetup) {
   return { mode: setup.mode, actions, warnings };
 }
 
-export async function initProject({ cwd, templateRoot, target, tracker, force, gitSetup }) {
+function packageDirFromName(targetDir, packageName) {
+  return path.join(targetDir, "node_modules", ...packageName.split("/"));
+}
+
+async function ensureRuntimePackageInstalled({ targetDir, packageName, packageVersion }) {
+  const installDir = packageDirFromName(targetDir, packageName);
+  if (await directoryExists(installDir)) {
+    return { installedNow: false, installDir };
+  }
+
+  const spec = packageVersion ? `${packageName}@${packageVersion}` : packageName;
+  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  await runCommand(npmCommand, ["install", "-D", spec], targetDir);
+  return { installedNow: true, installDir };
+}
+
+export async function initProject({
+  cwd,
+  templateRoot,
+  target,
+  tracker,
+  force,
+  gitSetup,
+  packageName = "@k0t0vich/meta-agents-template",
+  packageVersion = "",
+}) {
   const targetDir = resolveTargetDir(cwd, target);
   const exists = await directoryExists(targetDir);
-
-  if (exists) {
-    const empty = await isDirectoryEmpty(targetDir);
-    if (!empty && !force) {
-      throw new Error(`target directory is not empty: ${targetDir}. Use --force to overwrite.`);
-    }
-  } else {
+  if (!exists) {
     await fs.mkdir(targetDir, { recursive: true });
   }
 
-  await fs.cp(templateRoot, targetDir, {
-    recursive: true,
+  const packageJson = await mergePackageJsonMeta({
+    targetDir,
+    packageName,
+    packageVersion,
     force,
-    errorOnExist: !force,
+  });
+  const runtimePackage = await ensureRuntimePackageInstalled({
+    targetDir,
+    packageName,
+    packageVersion,
   });
 
   const projectName = path.basename(targetDir);
-  await replacePlaceholders(targetDir, {
-    PROJECT_NAME: projectName,
-    DEFAULT_TRACKER: tracker,
+  const config = await syncConfigFiles({
+    templateRoot,
+    targetDir,
+    values: {
+      PROJECT_NAME: projectName,
+      DEFAULT_TRACKER: tracker,
+    },
+    force,
   });
 
+  const agents = await upsertAgentsLinks(targetDir, packageName);
   const git = await setupGit(targetDir, gitSetup);
-  return { targetDir, git };
+
+  return {
+    targetDir,
+    git,
+    packageJson,
+    runtimePackage,
+    config,
+    agents,
+  };
 }