@icebreakers/monorepo-templates 2.0.2 → 2.0.4

package/assets/.agents/skills/repoctl/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: repoctl
-description: Create and maintain pnpm/Turborepo workspaces with repoctl. Use when the user says 使用 repoctl 创建项目, create a monorepo, pnpm create repoctl, scaffold Vue/Hono/tsdown/vitepress, or run repo init/doctor/new/check.
+description: Create and maintain pnpm/Turborepo workspaces with repoctl. Use when the user says 使用 repoctl 创建项目, create a monorepo, pnpm create repoctl@latest, scaffold Vue/Hono/tsdown/vitepress, or run repo init/doctor/new/check.
 ---
 
 # repoctl
@@ -9,17 +9,22 @@ The package name is `repoctl`. The command is `repo`.
 
 ## Empty directory
 
-Do not prompt. Map the request to template keys, then:
+Create into a new or empty directory outside the repoctl source workspace. Do
+not add a business project under the source checkout, and do not point the
+create command at a non-empty directory unless the user explicitly asks to
+replace it with `--force`. Do not prompt. Map the request to template keys,
+then:
 
 ```bash
-pnpm create repoctl <dir> -- --yes --templates <keys>
+pnpm create repoctl@latest <dir> -- --yes --templates <keys>
 cd <dir>
+corepack enable
 pnpm install
 pnpm exec repo init
 pnpm exec repo doctor
 ```
 
-`npm create` and `pnpm create` need the extra `--` before flags. `npx create-repoctl <dir> --yes --templates <keys>` does not.
+`npm create` and `pnpm create` need the extra `--` before flags. `npx create-repoctl@latest <dir> --yes --templates <keys>` does not.
 
 | User intent              | `--templates` key  |
 | ------------------------ | ------------------ |

package/assets/.agents/skills/repoctl/references/commands.md

@@ -193,7 +193,8 @@ Usage:
 
 ## skills sync
 
-Purpose: sync the `repoctl` skill into global agent skill directories.
+Purpose: sync the `repoctl` skill into global agent skill directories. Use
+`--all` when all supported agents should receive the same skill version.
 Usage:
 
 - pnpm exec repo skills sync

package/assets/.github/workflows/ci.yml

@@ -78,6 +78,10 @@ jobs:
       - name: Test
         run: pnpm test
 
+      - name: Check packaged monorepo creation
+        if: ${{ matrix.os == 'ubuntu-latest' && matrix.node-version == 22 }}
+        run: pnpm test:packaged-create
+
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         env:

package/assets/.github/workflows/release.yml

@@ -83,3 +83,14 @@ jobs:
           REPO_RELEASE_VERSION: ${{ inputs.version }}
           REPO_RELEASE_DRY_RUN: ${{ inputs.dry-run }}
         run: pnpm exec repo release ci
+
+      - name: Preserve npm publish progress
+        if: ${{ always() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: npm-publish-progress-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            pnpm-publish-summary.json
+            repoctl-publish-progress.json
+          if-no-files-found: ignore
+          retention-days: 14

package/assets/AGENTS.md

@@ -22,6 +22,21 @@ pnpm exec repo new <name> --template <key>
 
 Preview without writing files: `pnpm exec repo new <name> --template <key> --dry-run`.
 
+## Create a new project
+
+If the user asks you to create a new business project, do not add it inside an
+existing unrelated repository. Use a new or empty directory outside the repoctl
+source checkout. Start a new workspace with:
+
+```bash
+pnpm create repoctl@latest <dir> -- --yes --templates <keys>
+cd <dir>
+corepack enable
+pnpm install
+pnpm exec repo init
+pnpm exec repo doctor
+```
+
 ## Verify
 
 ```bash
@@ -38,5 +53,5 @@ pnpm exec repo check
 ## Requirements
 
 - Node.js 22.13 or newer
-- pnpm
+- pnpm (run `corepack enable` so the declared workspace version is used)
 - CLI output is English by default; `--lang zh-CN` or `REPOCTL_LANG=zh-CN` selects Simplified Chinese

package/assets/CLAUDE.md

@@ -7,8 +7,14 @@ Follow `AGENTS.md` in the workspace root. Create packages with
 `pnpm exec repo doctor` and `pnpm exec repo check`.
 
 If you were asked to create a new business project, do not add it inside an
-existing unrelated repository. Use:
+existing unrelated repository. Use a new or empty directory outside the repoctl
+source checkout:
 
 ```bash
-pnpm create repoctl <dir> -- --yes --templates <keys>
+pnpm create repoctl@latest <dir> -- --yes --templates <keys>
+cd <dir>
+corepack enable
+pnpm install
+pnpm exec repo init
+pnpm exec repo doctor
 ```

package/assets/gitignore

@@ -40,3 +40,9 @@ config.ts.timestamp-*.mjs
 
 # local AI task artifacts
 /.qoder/
+
+# release diagnostics (retained as CI artifacts)
+/pnpm-publish-summary.json
+/repoctl-publish-progress.json
+/pnpm-publish-summary.json.*.tmp
+/repoctl-publish-progress.json.*.tmp

package/assets/npmrc

@@ -0,0 +1,20 @@
+# 文档地址: https://pnpm.io/npmrc
+## 默认地址
+registry=https://registry.npmjs.org/
+## 可使用国内镜像地址
+# registry=http://registry.npmmirror.com/
+
+## Git 配置
+git-checks=false
+
+## 包管理器配置
+package-manager-strict=true
+package-manager-strict-version=true
+
+## 依赖处理
+auto-install-peers=true
+strict-peer-dependencies=false
+resolution-mode=highest
+
+## 部分场景可能需要开启此配置
+# shamefully-hoist=true

package/assets/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "version": "0.0.0",
   "private": true,
-  "packageManager": "pnpm@12.5.1",
+  "packageManager": "pnpm@12.6.0",
   "description": "Source workspace for repoctl and Icebreaker's shared development packages",
   "author": "ice breaker <hi@sonofmagic.top>",
   "license": "MIT",
@@ -28,7 +28,7 @@
   "scripts": {
     "build": "turbo run build",
     "tooling:build": "turbo run build --filter=@icebreakers/monorepo --filter=repoctl",
-    "dev": "turbo run dev --parallel",
+    "dev": "turbo run dev --concurrency=20",
     "test": "node -e \"require('node:fs').mkdirSync('coverage/.tmp', { recursive: true })\" && pnpm check:no-tracked-build-artifacts && vitest run && pnpm test:types",
     "test:packaged-doctor": "node scripts/smoke-packaged-doctor.mjs",
     "test:dev": "node -e \"require('node:fs').mkdirSync('coverage/.tmp', { recursive: true })\" && pnpm check:no-tracked-build-artifacts && vitest",

package/assets/pnpm-workspace.yaml

@@ -4,6 +4,7 @@ packages:
   - templates/*
   - "!**/test/**"
 minimumReleaseAge: 0
+pmOnFail: error
 versioning:
   changelog:
     storage: repository

package/assets/turbo.json

@@ -40,6 +40,9 @@
       "outputs": []
     },
     "dev": {
+      "dependsOn": [
+        "^build"
+      ],
       "cache": false,
       "persistent": true
     },

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { t as prepareAssets } from "./prepare-zIcRa4-K.mjs";
+import { t as prepareAssets } from "./prepare-BapI8ioj.mjs";
 import process from "node:process";
 //#region src/cli.ts
 async function main() {

package/dist/index.d.mts

@@ -23,13 +23,16 @@ interface SuggestTemplateKeyOptions extends GetTemplateChoicesOptions {
   keys?: readonly string[];
 }
 //#endregion
+//#region src/package-manager/index.d.ts
+export declare function getWorkspacePackageManager(): Promise<string>;
+//#endregion
 //#region src/paths.d.ts
 export declare const packageDir: string;
 export declare const templatesDir: string;
 export declare const assetsDir: string;
 export declare const skeletonDir: string;
 //#endregion
-//#region src/prepare.d.ts
+//#region src/prepare/index.d.ts
 interface PrepareAssetsOptions {
   overwriteExisting?: boolean;
   silent?: boolean;
@@ -76,6 +79,7 @@ export declare function execaCommand(command: string, options?: RunCommandOption
 //#region src/utils/gitignore.d.ts
 export declare function toPublishGitignorePath(input: string): string;
 export declare function toWorkspaceGitignorePath(input: string): string;
+export declare function toWorkspaceAssetPath(input: string): string;
 export declare function isGitignoreFile(name: string): boolean;
 //#endregion
 //#region src/utils/template-filter.d.ts

package/dist/index.mjs

@@ -1,11 +1,22 @@
-import { a as toPublishGitignorePath, c as assetsDir, d as templatesDir, f as assetTargets$1, i as isGitignoreFile, l as packageDir, n as createTemplateCopyFilter, o as toWorkspaceGitignorePath, p as getAssetTargets$1, r as shouldSkipTemplatePath, s as templateChoices$1, t as prepareAssets, u as skeletonDir } from "./prepare-zIcRa4-K.mjs";
+import { a as isGitignoreFile, c as toWorkspaceGitignorePath, d as packageDir, f as skeletonDir, h as getAssetTargets$1, i as shouldSkipTemplatePath, l as templateChoices$1, m as assetTargets$1, n as sanitizePublishedWorkspaceContent, o as toPublishGitignorePath, p as templatesDir, r as createTemplateCopyFilter, s as toWorkspaceAssetPath, t as prepareAssets, u as assetsDir } from "./prepare-BapI8ioj.mjs";
 import path from "node:path";
-import fs, { access, open, rm } from "node:fs/promises";
+import fs, { access, open, readFile, rm } from "node:fs/promises";
 import exec from "nanoexec";
 import checkbox from "@inquirer/checkbox";
 import input from "@inquirer/input";
 import select from "@inquirer/select";
 import { Command, program } from "commander";
+//#region src/package-manager/read.ts
+const packageManagerPattern = /^pnpm@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+function validateWorkspacePackageManager(value, source) {
+	if (typeof value !== "string" || !packageManagerPattern.test(value)) throw new Error(`Invalid packageManager in ${source}; expected a pnpm version such as pnpm@12.5.1.`);
+	return value;
+}
+async function readPackageManagerFromManifest(manifestPath) {
+	const raw = await fs.readFile(manifestPath, "utf8");
+	return validateWorkspacePackageManager(JSON.parse(raw)?.packageManager, manifestPath);
+}
+//#endregion
 //#region src/runtime-assets.ts
 const lockFileName = ".prepare-assets.lock";
 const lockPollIntervalMs = 200;
@@ -33,7 +44,55 @@ async function isPrepared() {
 		path.join(assetsDir, "LICENSE"),
 		path.join(templatesDir, "tsdown")
 	];
-	return (await Promise.all(checks.map(pathExists))).every(Boolean);
+	if (!(await Promise.all(checks.map(pathExists))).every(Boolean)) return false;
+	const sourceRoot = path.resolve(packageDir, "..", "..");
+	const sourceManifest = path.join(sourceRoot, "package.json");
+	let sourcePackage;
+	try {
+		sourcePackage = JSON.parse(await readFile(sourceManifest, "utf8"));
+	} catch (error) {
+		if (error.code === "ENOENT") return true;
+		throw error;
+	}
+	if (sourcePackage.name !== "repoctl-workspace") return true;
+	const [sourcePackageManager, sourceNpmrc, sourceWorkspace] = await Promise.all([
+		readPackageManagerFromManifest(sourceManifest),
+		readFile(path.join(sourceRoot, ".npmrc"), "utf8"),
+		readFile(path.join(sourceRoot, "pnpm-workspace.yaml"), "utf8")
+	]);
+	let preparedPackageManager;
+	let preparedNpmrc;
+	let preparedWorkspace;
+	let sourceAgentContent;
+	let preparedAgentContent;
+	let sourceSkillContent;
+	let preparedSkillContent;
+	try {
+		const sourceAgentFiles = ["AGENTS.md", "CLAUDE.md"];
+		const [prepared, sourceAgents, preparedAgents, sourceSkill, preparedSkill] = await Promise.all([
+			Promise.all([
+				readPackageManagerFromManifest(path.join(assetsDir, "package.json")),
+				readFile(path.join(assetsDir, "npmrc"), "utf8"),
+				readFile(path.join(assetsDir, "pnpm-workspace.yaml"), "utf8")
+			]),
+			Promise.all(sourceAgentFiles.map((filename) => readFile(path.join(sourceRoot, "packages/monorepo/assets", filename), "utf8"))),
+			Promise.all(sourceAgentFiles.map((filename) => readFile(path.join(assetsDir, filename), "utf8"))),
+			readFile(path.join(sourceRoot, "packages/monorepo/resources/skills/repoctl/SKILL.md"), "utf8"),
+			readFile(path.join(assetsDir, ".agents/skills/repoctl/SKILL.md"), "utf8")
+		]);
+		preparedPackageManager = prepared[0];
+		preparedNpmrc = prepared[1];
+		preparedWorkspace = prepared[2];
+		sourceAgentContent = sourceAgents;
+		preparedAgentContent = preparedAgents;
+		sourceSkillContent = sourceSkill;
+		preparedSkillContent = preparedSkill;
+	} catch (error) {
+		if (error.code === "ENOENT" || error instanceof SyntaxError) return false;
+		if (error instanceof Error && error.message.startsWith("Invalid packageManager in ")) return false;
+		throw error;
+	}
+	return sourcePackageManager === preparedPackageManager && sourceNpmrc === preparedNpmrc && sanitizePublishedWorkspaceContent(sourceWorkspace) === preparedWorkspace && sourceAgentContent.every((content, index) => content === preparedAgentContent[index]) && sourceSkillContent === preparedSkillContent;
 }
 async function waitForPrepared() {
 	const deadline = Date.now() + lockTimeoutMs;
@@ -69,6 +128,12 @@ async function ensureTemplateAssetsPrepared() {
 	await ensurePromise;
 }
 //#endregion
+//#region src/package-manager/index.ts
+async function getWorkspacePackageManager() {
+	await ensureTemplateAssetsPrepared();
+	return readPackageManagerFromManifest(path.join(assetsDir, "package.json"));
+}
+//#endregion
 //#region src/scaffold.ts
 async function isEmptyDir(dir) {
 	try {
@@ -141,7 +206,10 @@ async function scaffoldWorkspace(options) {
 	if (includeAssets && path.resolve(assetsDir$1) === path.resolve(assetsDir) || templateKeys.length > 0 && path.resolve(templatesDir$1) === path.resolve(templatesDir)) await ensureTemplateAssetsPrepared();
 	if (targetMode === "prepare") await prepareTargetDir(targetDir, { force });
 	else if (targetMode === "ensure") await fs.mkdir(targetDir, { recursive: true });
-	if (includeAssets) await copyDirContents(assetsDir$1, targetDir, { rootDir: assetsDir$1 });
+	if (includeAssets) await copyDirContents(assetsDir$1, targetDir, {
+		rootDir: assetsDir$1,
+		renameEntry: toWorkspaceAssetPath
+	});
 	if (!templateKeys.length) return;
 	const selections = new Set(templateKeys);
 	for (const template of templateChoices$1) {
@@ -258,4 +326,4 @@ const templateSourceMap = Object.fromEntries(templateChoices.map((item) => [item
 const templateTargetMap = Object.fromEntries(templateChoices.map((item) => [item.key, item.target]));
 const templateMap = templateSourceMap;
 //#endregion
-export { Command, assetTargets, assetsDir, checkbox, createTemplateCopyFilter, ensureTemplateAssetsPrepared, execaCommand, getAssetTargets, getTemplateChoice, getTemplateChoices, getTemplateDefinition, getTemplateKeys, getTemplateSource, getTemplateTarget, input, isGitignoreFile, isTemplateCategory, isTemplateKey, packageDir, prepareAssets, program, runCommand, scaffoldTemplate, scaffoldWorkspace, select, shouldSkipTemplatePath, skeletonDir, suggestTemplateKey, templateCategories, templateChoices, templateMap, templateSourceMap, templateTargetMap, templatesDir, toPublishGitignorePath, toWorkspaceGitignorePath };
+export { Command, assetTargets, assetsDir, checkbox, createTemplateCopyFilter, ensureTemplateAssetsPrepared, execaCommand, getAssetTargets, getTemplateChoice, getTemplateChoices, getTemplateDefinition, getTemplateKeys, getTemplateSource, getTemplateTarget, getWorkspacePackageManager, input, isGitignoreFile, isTemplateCategory, isTemplateKey, packageDir, prepareAssets, program, runCommand, scaffoldTemplate, scaffoldWorkspace, select, shouldSkipTemplatePath, skeletonDir, suggestTemplateKey, templateCategories, templateChoices, templateMap, templateSourceMap, templateTargetMap, templatesDir, toPublishGitignorePath, toWorkspaceAssetPath, toWorkspaceGitignorePath };

package/dist/{prepare-zIcRa4-K.mjs → prepare-BapI8ioj.mjs}

@@ -128,6 +128,9 @@ function toPublishGitignorePath(input) {
 function toWorkspaceGitignorePath(input) {
 	return replaceBasename(input, publishBasename, workspaceBasename);
 }
+function toWorkspaceAssetPath(input) {
+	return replaceBasename(toWorkspaceGitignorePath(input), "npmrc", ".npmrc");
+}
 function isGitignoreFile(name) {
 	return toPublishGitignorePath(name) !== name || toWorkspaceGitignorePath(name) !== name;
 }
@@ -165,8 +168,16 @@ function createTemplateCopyFilter(rootDir) {
 	return (src) => !shouldSkipTemplatePath(rootDir, src);
 }
 //#endregion
-//#region src/prepare.ts
-const huskySkippedEntryPattern = /[\\/]_$/;
+//#region src/prepare/published.ts
+function sanitizePublishedManifestContent(content) {
+	const manifest = JSON.parse(content);
+	if (manifest.scripts) {
+		for (const name of Object.keys(manifest.scripts)) if (name.startsWith("dev:") || name === "test:dev-scenarios" || name === "test:worker-types" || name === "test:packaged-create") delete manifest.scripts[name];
+		manifest.scripts["dev"] = "turbo run dev --concurrency=20";
+		if (manifest.scripts["test"]) manifest.scripts["test"] = manifest.scripts["test"].replace(" && pnpm test:dev-scenarios", "");
+	}
+	return `${JSON.stringify(manifest, null, 2)}\n`;
+}
 const publishedToolingConfigs = {
 	"commitlint.config.ts": [
 		`import { defineCommitlintConfig } from 'repoctl/tooling'`,
@@ -224,6 +235,12 @@ function sanitizePublishedWorkspaceContent(content) {
 	}
 	return changed ? YAML.stringify(workspace) : content;
 }
+//#endregion
+//#region src/prepare/index.ts
+const huskySkippedEntryPattern = /[\\/]_$/;
+function toPublishedAssetPath(target) {
+	return target === ".npmrc" ? "npmrc" : toPublishGitignorePath(target);
+}
 async function pathExists(targetPath) {
 	try {
 		await fs.access(targetPath);
@@ -294,9 +311,17 @@ async function copyAssets(repoRoot, overwriteExisting) {
 		const repoAsset = path$1.join(repoRoot, target);
 		const from = publishedAgentSourceFiles.has(target) || !await pathExists(repoAsset) ? packageAsset : repoAsset;
 		if (!await pathExists(from)) continue;
-		const to = path$1.join(assetsDir, toPublishGitignorePath(target));
+		const to = path$1.join(assetsDir, toPublishedAssetPath(target));
 		const stats = await fs.stat(from);
-		await copyEntry(from, to, overwriteExisting, target === ".husky" ? (src) => !huskySkippedEntryPattern.test(src) : void 0);
+		const filter = target === ".husky" ? (src) => !huskySkippedEntryPattern.test(src) : void 0;
+		const refreshManagedMetadata = [
+			"package.json",
+			".npmrc",
+			"pnpm-workspace.yaml",
+			"AGENTS.md",
+			"CLAUDE.md"
+		].includes(target);
+		await copyEntry(from, to, overwriteExisting || refreshManagedMetadata, filter);
 		if (target === "tsconfig.json") await fs.writeFile(to, `${JSON.stringify({
 			extends: "repoctl/tsconfig.json",
 			files: []
@@ -310,10 +335,10 @@ async function writePublishedToolingConfigs() {
 		if (await pathExists(targetPath)) await fs.writeFile(targetPath, content);
 	}));
 }
-async function writePublishedAgentSkill(repoRoot, overwriteExisting) {
+async function writePublishedAgentSkill(repoRoot) {
 	const skillFrom = path$1.join(repoRoot, "packages/monorepo/resources/skills/repoctl");
 	if (!await pathExists(skillFrom)) return;
-	await copyEntry(skillFrom, path$1.join(assetsDir, ".agents", "skills", "repoctl"), overwriteExisting);
+	await copyEntry(skillFrom, path$1.join(assetsDir, ".agents", "skills", "repoctl"), true);
 }
 async function sanitizePublishedWorkspace() {
 	const workspacePath = path$1.join(assetsDir, "pnpm-workspace.yaml");
@@ -331,7 +356,7 @@ async function removeSourceRepoReleaseToolingBuildStep() {
 	const nextContent = removeSourceRepoReleaseToolingBuildStepContent(content);
 	if (nextContent !== content) await fs.writeFile(releaseWorkflowPath, nextContent, "utf8");
 }
-async function removeSourceRepoWorkerTypeChecks() {
+async function removeSourceRepoChecks() {
 	const workflowPath = path$1.join(assetsDir, ".github/workflows/ci.yml");
 	if (await pathExists(workflowPath)) {
 		const workflow = await fs.readFile(workflowPath, "utf8");
@@ -339,9 +364,8 @@ async function removeSourceRepoWorkerTypeChecks() {
 	}
 	const manifestPath = path$1.join(assetsDir, "package.json");
 	if (await pathExists(manifestPath)) {
-		const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
-		delete manifest.scripts?.["test:worker-types"];
-		await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+		const content = await fs.readFile(manifestPath, "utf8");
+		await fs.writeFile(manifestPath, sanitizePublishedManifestContent(content));
 	}
 }
 async function copyTemplates(repoRoot, overwriteExisting) {
@@ -360,14 +384,15 @@ async function prepareAssets(options = {}) {
 	if (!await pathExists(path$1.join(repoRoot, "templates"))) return;
 	await resetDir(assetsDir, overwriteExisting);
 	await resetDir(templatesDir, overwriteExisting);
+	await fs.rm(path$1.join(assetsDir, ".npmrc"), { force: true });
 	await copyAssets(repoRoot, overwriteExisting);
 	await sanitizePublishedWorkspace();
 	await removePublishedReleaseState();
 	await writePublishedToolingConfigs();
-	await writePublishedAgentSkill(repoRoot, overwriteExisting);
+	await writePublishedAgentSkill(repoRoot);
 	await removeSourceRepoReleaseToolingBuildStep();
-	await removeSourceRepoWorkerTypeChecks();
+	await removeSourceRepoChecks();
 	await copyTemplates(repoRoot, overwriteExisting);
 }
 //#endregion
-export { toPublishGitignorePath as a, assetsDir as c, templatesDir as d, assetTargets as f, isGitignoreFile as i, packageDir as l, createTemplateCopyFilter as n, toWorkspaceGitignorePath as o, getAssetTargets as p, shouldSkipTemplatePath as r, templateChoices as s, prepareAssets as t, skeletonDir as u };
+export { isGitignoreFile as a, toWorkspaceGitignorePath as c, packageDir as d, skeletonDir as f, getAssetTargets as h, shouldSkipTemplatePath as i, templateChoices as l, assetTargets as m, sanitizePublishedWorkspaceContent as n, toPublishGitignorePath as o, templatesDir as p, createTemplateCopyFilter as r, toWorkspaceAssetPath as s, prepareAssets as t, assetsDir as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@icebreakers/monorepo-templates",
   "type": "module",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Built-in project templates and managed workspace assets for repoctl",
   "author": "ice breaker <hi@sonofmagic.top>",
   "license": "MIT",

package/templates/client/package.json

@@ -60,7 +60,7 @@
     "@vitejs/plugin-vue-jsx": "^5.1.6",
     "@vue/tsconfig": "^0.9.1",
     "consola": "^3.4.2",
-    "hono": "^4.13.8",
+    "hono": "^4.13.9",
     "tailwindcss": "^4.3.3",
     "typescript": "~6.0.3",
     "vite": "^8.3.0",

package/templates/server/package.json

@@ -66,7 +66,7 @@
   "devDependencies": {
     "@hono/node-server": "^2.1.1",
     "consola": "^3.4.2",
-    "hono": "^4.13.8",
+    "hono": "^4.13.9",
     "tsdown": "0.23.0",
     "wrangler": "^4.135.0",
     "zod": "^4.6.5"

package/templates/vitepress/ai/create.md

@@ -1,5 +1,5 @@
 ---
-description: Non-interactive recipe for AI agents to create a repoctl workspace with pnpm create repoctl --yes.
+description: Non-interactive recipe for AI agents to create a repoctl workspace with pnpm create repoctl@latest --yes.
 outline: deep
 ---
 
@@ -9,18 +9,22 @@ Use this page when an agent is asked to create a new project with repoctl.
 
 ## Empty directory
 
-Do not prompt. Run:
+Use a new or empty directory outside the repoctl source checkout. Do not add a
+business project inside the source workspace, and do not use a non-empty target
+unless the user explicitly asks to replace it with `--force`. Do not prompt.
+Run:
 
 ```bash
-pnpm create repoctl <dir> -- --yes --templates <keys>
+pnpm create repoctl@latest <dir> -- --yes --templates <keys>
 cd <dir>
+corepack enable
 pnpm install
 pnpm exec repo init
 pnpm exec repo doctor
 ```
 
 `npm create repoctl@latest <dir> -- --yes --templates <keys>` and
-`npx create-repoctl <dir> --yes --templates <keys>` are equivalent.
+`npx create-repoctl@latest <dir> --yes --templates <keys>` are equivalent.
 `pnpm create` and `npm create` need the extra `--` before flags.
 
 ## Template keys

package/templates/vitepress/ai/index.md

@@ -23,7 +23,7 @@ repoctl publishes AI-readable documentation alongside the human site.
 - `/llms.txt`: compact English index and product summary.
 - `/llms-full.txt`: combined page content when a larger context is appropriate.
 - `/zh/`: Simplified Chinese documentation.
-- [Create a project](./create.md): non-interactive `pnpm create repoctl --yes` recipe.
+- [Create a project](./create.md): non-interactive `pnpm create repoctl@latest --yes` recipe.
 - [llms.txt Guide](./llms-txt.md): usage and maintenance rules.
 
 ## Using It In AI Tools

package/templates/vitepress/tasks/release.md

@@ -26,6 +26,21 @@ The release report names the packages that will change, the version decisions, a
 - Fixed group mismatch: inspect the package relationships before editing versions.
 - Registry authentication failure: refresh the local token and rerun the publish step; do not commit credentials.
 
+## Partial publication and registry visibility
+
+The publisher attempts uploads at most three times, waiting 20 and 40 seconds before refreshing registry state and selecting retry packages. An exact version with explicit upload acceptance is never uploaded again during that invocation, even if `npm view` cannot find it yet. Ordinary permission errors and 404 responses without transient-failure evidence fail immediately. Conflicts require read-only registry confirmation.
+
+Accepted uploads must become queryable before post-publish hooks, Git tags, GitHub Releases, or prerelease pushes proceed. Visibility checks query pending versions every 10 seconds for up to five minutes. A timeout exits unsuccessfully and lists pending versions.
+
+Two files remain in the workspace root:
+
+- `pnpm-publish-summary.json`: cumulative `publishedPackages`, including accepted uploads and registry-confirmed versions. On failure, this file alone does not prove that every listed version is available.
+- `repoctl-publish-progress.json`: `schemaVersion: 1`, `candidates`, `acceptedPackages`, `confirmedPackages`, and `status` (`publishing`, `confirming`, `complete`, or `failed`). Accepted versions missing from `confirmedPackages` still need visibility confirmation.
+
+The managed Release workflow uploads both files as `npm-publish-progress-<run_id>-<run_attempt>` on success or failure, retained for 14 days. Missing reports are ignored. After upgrading repoctl, run `repo upgrade` to refresh managed workflows; custom workflows can add the same upload step.
+
+After a failure, download the artifact and reconcile exact versions with `npm view <name>@<version> version`. Continue read-only checks for accepted but unconfirmed versions instead of rerunning the entire release lifecycle. Use the workflow's `reconcile` mode to repair metadata for visible versions, and `publish-unpublished` only for versions verified as still requiring upload. Reports are diagnostic: a new invocation does not trust old reports or automatically resume across processes.
+
 ## Next
 
 Read [publishing and changelogs](/learn/monorepo/publish) for repository policy and [reports and output](/tasks/reports) for CI artifacts.

package/templates/vitepress/zh/ai/create.md

@@ -1,5 +1,5 @@
 ---
-description: 给 AI 代理用的非交互配方：pnpm create repoctl --yes 创建 repoctl 工作区。
+description: 给 AI 代理用的非交互配方：pnpm create repoctl@latest --yes 创建 repoctl 工作区。
 outline: deep
 ---
 
@@ -9,18 +9,21 @@ outline: deep
 
 ## 空目录
 
-不要提问。直接运行：
+目标目录应是 repoctl 源仓库之外的新目录或空目录。不要把业务项目放进
+源仓库，也不要在非空目录上运行，除非用户明确要求使用 `--force` 覆盖。
+不要提问，直接运行：
 
 ```bash
-pnpm create repoctl <dir> -- --yes --templates <keys>
+pnpm create repoctl@latest <dir> -- --yes --templates <keys>
 cd <dir>
+corepack enable
 pnpm install
 pnpm exec repo init
 pnpm exec repo doctor
 ```
 
 等价命令：`npm create repoctl@latest <dir> -- --yes --templates <keys>` 与
-`npx create-repoctl <dir> --yes --templates <keys>`。
+`npx create-repoctl@latest <dir> --yes --templates <keys>`。
 `pnpm create` / `npm create` 的 flag 前必须加 `--`。
 
 ## 模板 key

package/templates/vitepress/zh/ai/index.md

@@ -12,7 +12,7 @@ AI 文档入口用于给 Cursor、Claude Code、Codex 和其他 AI 编程工具
 | ------------------------------ | ------------------------------------------------ |
 | `/llms.txt`                    | 轻量文档索引，适合先交给 AI 工具判断要读哪些页面 |
 | `/llms-full.txt`               | 合并后的完整文档，适合需要一次性提供上下文的场景 |
-| [创建项目](./create.md)        | 非交互 `pnpm create repoctl --yes` 配方          |
+| [创建项目](./create.md)        | 非交互 `pnpm create repoctl@latest --yes` 配方   |
 | [llms.txt 说明](./llms-txt.md) | 维护约定、访问方式和页面 frontmatter 要求        |
 
 ## 2. 在 AI 工具里怎么用

package/templates/vitepress/zh/learn/monorepo/publish.md

@@ -33,7 +33,7 @@ CI 将版本号、各包 `CHANGELOG.md` 和 `.changeset/ledger.yaml` 提交到 R
 pnpm publish -r --report-summary --provenance --no-git-checks
 ```
 
-pnpm 根据 registry 中已有的版本自动跳过已发布包。CI 读取 `pnpm-publish-summary.json` 创建 `package@version` tag 和 GitHub Release，发布操作可以安全重试。
+pnpm 根据 registry 中已有的版本自动跳过已发布包。CI 读取 `pnpm-publish-summary.json` 创建 `package@version` tag 和 GitHub Release，发布器在本次调用内保留已接收上传的版本，确认 registry 可见性后再执行后置流程；失败后的处理见[部分发布与 registry 延迟](/zh/tasks/release#部分发布与-registry-延迟)。
 
 ## Workspace versioning 配置
 

package/templates/vitepress/zh/learn/tools/changeset.md

@@ -38,7 +38,7 @@ pnpm version -r
 pnpm publish -r --report-summary --provenance --no-git-checks
 ```
 
-pnpm 会跳过 registry 中已经存在的版本，并把新发布包写入 `pnpm-publish-summary.json`。CI 根据 summary 创建 `package@version` Git tag 和 GitHub Release，因此重复执行不会重新发布已存在版本。
+pnpm 会跳过 registry 中已经存在的版本，并把新发布包写入 `pnpm-publish-summary.json`。CI 根据 summary 创建 `package@version` Git tag 和 GitHub Release，发布器会保留本次调用的部分成功状态，等待 registry 确认可见后再创建元数据；不要在传播延迟期间直接重跑整个生命周期，详见[发布任务](/zh/tasks/release)。
 
 本地推荐使用 repoctl 包装命令：
 

package/templates/vitepress/zh/tasks/release.md

@@ -26,6 +26,21 @@ repo release --dry-run
 - 固定版本组不一致：先检查包之间的关系，再修改版本。
 - registry 认证失败：刷新本地 token 后重试，不要提交凭据。
 
+## 部分发布与 registry 延迟
+
+发布器最多尝试上传 3 次，重试前分别等待 20、40 秒并重新查询 registry。明确上传成功的精确版本不会再次上传，即使此时 `npm view` 暂不可查询。普通权限错误和没有瞬时故障依据的 404 会直接失败；冲突只能通过只读对账确认，不能当作成功。
+
+已接收上传的版本需要确认可查询后，才会执行后置 hooks、Git tag 和 GitHub Release。确认期间每 10 秒查询待确认版本，最多等待 5 分钟；超时会非零退出并列出待确认版本。
+
+工作区根目录保留两份文件：
+
+- `pnpm-publish-summary.json`：跨尝试累计的 `publishedPackages`，包括已接收上传和 registry 已确认的版本；失败时不能仅凭此文件认定所有版本已可用。
+- `repoctl-publish-progress.json`：`schemaVersion: 1`，记录 `candidates`、`acceptedPackages`、`confirmedPackages` 及 `status`（`publishing`、`confirming`、`complete`、`failed`）。已接收但未确认的版本是前两种成功状态之差。
+
+受管 Release 工作流会在发布成功或失败后上传 `npm-publish-progress-<run_id>-<run_attempt>` artifact，保留 14 天；没有清单时跳过上传。现有项目升级 repoctl 后运行 `repo upgrade` 更新受管工作流；自定义工作流可自行添加相同上传步骤。
+
+失败后先下载 artifact，并用 `npm view <name>@<version> version` 对账。对于已接收但未确认的版本，继续只读确认，不要直接重跑整个发布生命周期。确认已经可用的版本可通过工作流的 `reconcile` 模式补齐元数据；仅对核实仍未上传的版本使用 `publish-unpublished`。旧清单仅用于诊断，新调用不会自动信任旧清单或跨进程续传。
+
 ## 下一步
 
 阅读[发包与变更日志](/zh/learn/monorepo/publish)，再查看[报告与输出](/zh/tasks/reports)了解 CI 产物。