@yuchenrx/pmt-cli 0.1.2

package/AGENTS.md

@@ -0,0 +1,128 @@
+# AGENTS.md
+
+## Purpose
+- This file provides build, test, and style guidance for agentic coding.
+- Follow these conventions unless a user request overrides them.
+
+## Workspace
+- Root: `E:\study\node\md-cli`
+- Runtime: Bun (ESM, `type: module`).
+- Entry: `src/cli.ts`.
+
+## Build and Run
+- Run CLI locally: `bun src/cli.ts`
+- NPM script: `bun run pmt`
+- Build binary: `bun run build`
+- Build output: `dist/<cliName>.exe` (default: `dist/pmt.exe`)
+
+## Test
+- Run all tests: `bun test`
+- Run a single test file: `bun test tests/<file>.test.ts`
+- Run by name pattern (Bun supports filter): `bun test --filter "name"`
+- Coverage (optional): `bun test --coverage`
+
+## Lint/Format
+- No explicit lint or formatter configured.
+- Do not introduce new linters/formatters without request.
+
+## Repo Structure
+- `src/cli.ts` initializes Commander and registers commands.
+- `src/commands.ts` declares CLI commands and arguments.
+- `src/command-*.ts` holds command implementations.
+- `src/config.ts` loads/merges config and resolves paths.
+- `src/helpers.ts` provides filesystem/path helpers.
+- `src/link*.ts` handles link metadata and linking logic.
+- `src/completion.ts` handles shell completion.
+- `scripts/build.ts` builds the binary.
+- Tests live in `tests/*.test.ts`.
+
+## Configuration Files
+- Project config: `.promptslotrc.json` in repo root.
+- Global config: `~/.promptslotrc.json`.
+- Link store: `.promptslot-links.json` in repo root.
+- Index: `.promptslot-index.json` in repo root.
+
+## CLI Conventions
+- Use Commander `Command` with chained calls.
+- Use `.argument()` for positional arguments.
+- Use `.option()` only when truly optional.
+- Use async handlers: `.action(async () => { ... })`.
+- Set `process.exitCode = 1` on errors instead of throwing.
+- Print errors via `console.error`, success via `console.log`.
+
+## Imports and Modules
+- Use ESM import syntax.
+- Prefer `node:` prefix for Node builtins.
+- Prefer `import type` for types.
+- Avoid unused imports; keep import order stable.
+
+## Naming Conventions
+- Functions: lowerCamelCase.
+- Files: kebab-case for command files (`command-*.ts`).
+- Config keys: snake_case (e.g., `prompts_root`).
+- Link default name: `AGENTS.md`.
+
+## Error Handling
+- Use small `fail()` helpers that set `process.exitCode`.
+- Avoid throwing for normal CLI errors.
+- Return early after error reporting.
+- For filesystem errors, check existence explicitly before use.
+
+## Async and I/O
+- Prefer `fs.promises` APIs.
+- Avoid synchronous FS unless required (e.g., `spawnSync` for git).
+- When reading remote sources, treat them as read-only.
+
+## Completion
+- Autocomplete uses `omelette` and `enquirer` for interactive search.
+- Completion is initialized in `src/cli.ts`.
+- Avoid heavy work in completion handlers.
+
+## Link Behavior
+- `link` attempts hardlink -> symlink -> meta-link fallback.
+- Hard/soft links are real-time (filesystem-level).
+- Meta-link uses a header with source path + hash.
+- Meta-link content is read-only unless explicitly changed by CLI logic.
+
+## Index and Auto-Repair
+- Link index maps source -> targets and roots.
+- Auto-repair runs at CLI start and updates broken paths.
+- Do not scan full disks; use index roots only.
+
+## Testing Conventions
+- Use `bun:test` (`describe`, `it`, `expect`).
+- Keep tests deterministic and filesystem-safe.
+- Use `os.tmpdir()` for temp directories.
+- Clean up watchers or temporary resources in tests.
+
+## Style Notes
+- Keep functions small and focused.
+- Avoid deep nesting; use early returns.
+- Avoid inline comments unless needed for clarity.
+- Keep output messages user-facing and concise.
+
+## Changes to Avoid
+- Do not add new CLI commands unless requested.
+- Do not change config schema without migration logic.
+- Do not modify `dist/` outputs manually.
+- Do not add network dependencies without approval.
+
+## Single-Test Workflow
+- Use `bun test tests/xyz.test.ts`.
+- If needed, add `--filter` for a single case.
+
+## Release (GitHub Actions)
+- Tag push `vX.Y.Z` triggers build + release + npm publish.
+- Workflow sets `package.json` version from tag; uses `NPM_TOKEN` secret.
+
+
+## Notes on External Libraries
+- Commander for CLI parsing.
+- Cosmiconfig for configuration loading.
+- Enquirer for interactive selection.
+- Omelette for shell completion.
+
+## Platform Notes
+- Windows is the primary platform.
+- Prefer cross-platform APIs; avoid shell-specific commands.
+

package/README.md

@@ -0,0 +1,134 @@
+# pmt
+
+Prompt/spec manager CLI that keeps shared rules synchronized across projects.
+
+[中文文档](./README.zh.md)
+
+## What it does
+
+- Centralizes prompt/spec files in a global repo (`prompts_root`).
+- Creates link files in any project (hardlink -> symlink -> meta-link fallback).
+- Tracks link moves/renames in background (no full-disk scans).
+- Shows link status without scanning the filesystem.
+
+## Install
+
+### npm (Windows)
+
+```bash
+npm i -g @yuchenrx/pmt-cli
+```
+
+This package publishes a Windows binary. For other platforms, build from source.
+
+### From source
+
+```bash
+bun install
+```
+
+## Run (global)
+
+```bash
+pmt
+```
+
+## Run (dev)
+
+```bash
+bun run pmt
+```
+
+## Build
+
+```bash
+bun run build
+```
+
+Output: `dist/pmt.exe`
+
+## Quick Start
+
+### 1) Init
+
+Global prompt repo:
+
+```bash
+pmt init
+```
+
+`init` initializes the global prompt repo and runs `git init` under `prompts_root` if needed.
+
+### 2) Link
+
+Create a link file using the source filename as default:
+
+```bash
+pmt link 规范
+```
+
+Create to a specific path:
+
+```bash
+pmt link 规范 docs/AGENTS.md
+```
+
+Interactive search:
+
+```bash
+pmt link
+pmt link -i
+```
+
+### 3) Status
+
+```bash
+pmt status
+```
+
+Example output:
+
+```
+docs/AGENTS.md -> C:\...\prompts\规范.md [hardlink] ok
+AGENTS.md -> C:\...\prompts\rules.md [meta] missing
+roots: C:\repo, D:\shared
+```
+
+## Config
+
+Config files:
+
+- Project: `.promptslotrc.json`
+- Global: `~/.promptslotrc.json`
+- Link store: `.promptslot-links.json`
+- Link index: `.promptslot-index.json`
+
+Common keys:
+
+- `prompts_root`: global prompt repo directory
+- `prompts_dir`: project prompt directory (fallback)
+- `link_default`: default link filename
+- `sources`: name → file path/URL
+- `current`: active source name
+
+## Link modes
+
+1) **Hardlink**: real-time sync at filesystem level
+2) **Symlink**: real-time sync at filesystem level
+3) **Meta-link**: header + hash (used when linking is not possible)
+
+Meta-link is for read-only or cross-device cases (e.g. URL sources).
+
+## Rename tracking
+
+- A background rename daemon starts after creating a meta-link.
+- It only watches directories that already contain link files.
+- No full-disk scanning; updates `.promptslot-links.json` on rename.
+
+## CLI name override
+
+```bash
+CLI_NAME=pmt
+```
+
+

package/README.zh.md

@@ -0,0 +1,132 @@
+# pmt
+
+用于统一管理/同步规范与提示文件的 CLI。
+
+[English](./README.md)
+
+## 功能概述
+
+- 全局集中管理 prompt/spec 文件（`prompts_root`）。
+- 在任意项目创建 link 文件（硬链接 → 软链接 → meta-link 降级）。
+- 后台追踪 link 重命名/移动（只监听已有目录，不全盘扫描）。
+- `status` 查看所有 link 状态（不扫描磁盘）。
+
+## 安装
+
+### npm（Windows）
+
+```bash
+npm i -g @yuchenrx/pmt-cli
+```
+
+该包发布的是 Windows 二进制文件，其他平台请从源码构建。
+
+### 源码安装
+
+```bash
+bun install
+```
+
+## 运行（全局）
+
+```bash
+pmt
+```
+
+## 运行（开发）
+
+```bash
+bun run pmt
+```
+
+## 构建
+
+```bash
+bun run build
+```
+
+输出：`dist/pmt.exe`
+
+## 快速开始
+
+### 1）初始化
+
+全局 prompt 仓库：
+
+```bash
+pmt init
+```
+
+`init` 会在 `prompts_root` 下自动执行 `git init`（若未初始化）。
+
+### 2）创建链接
+
+默认使用源文件名作为目标名：
+
+```bash
+pmt link 规范
+```
+
+指定目标路径：
+
+```bash
+pmt link 规范 docs/AGENTS.md
+```
+
+交互搜索：
+
+```bash
+pmt link
+pmt link -i
+```
+
+### 3）查看状态
+
+```bash
+pmt status
+```
+
+示例输出：
+
+```
+docs/AGENTS.md -> C:\...\prompts\规范.md [hardlink] ok
+AGENTS.md -> C:\...\prompts\rules.md [meta] missing
+roots: C:\repo, D:\shared
+```
+
+## 配置
+
+配置文件：
+
+- 项目配置：`.promptslotrc.json`
+- 全局配置：`~/.promptslotrc.json`
+- 链接记录：`.promptslot-links.json`
+- 索引文件：`.promptslot-index.json`
+
+常用字段：
+
+- `prompts_root`：全局 prompt 仓库目录
+- `prompts_dir`：项目 prompts 目录（fallback）
+- `link_default`：默认 link 文件名
+- `sources`：name → 文件路径/URL
+- `current`：当前激活的 source 名
+
+## 链接模式
+
+1）**硬链接**：文件系统级实时同步
+2）**软链接**：文件系统级实时同步
+3）**Meta-link**：头部 + hash（无法链接时降级）
+
+Meta-link 用于跨盘、只读或 URL 等场景。
+
+## 重命名追踪
+
+- 创建 meta-link 后自动启动后台重命名守护。
+- 仅监听已有 link 文件所在目录。
+- 不做全盘扫描，仅更新 `.promptslot-links.json`。
+
+## CLI 名称覆盖
+
+```bash
+CLI_NAME=pmt
+```

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@yuchenrx/pmt-cli",
+  "version": "0.1.2",
+  "type": "module",
+  "bin": {
+    "pmt": "dist/pmt.exe"
+  },
+  "scripts": {
+    "pmt": "bun src/cli.ts",
+    "build": "bun scripts/build.ts",
+    "test": "bun test"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "README.zh.md",
+    "AGENTS.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/YuChenRX/pmt.git"
+  },
+  "homepage": "https://github.com/YuChenRX/pmt",
+  "bugs": {
+    "url": "https://github.com/YuChenRX/pmt/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "cosmiconfig": "^9.0.0",
+    "dotenv": "^17.2.3",
+    "enquirer": "^2.4.1",
+    "omelette": "^0.4.17",
+    "watcher": "^2.3.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6",
+    "@types/node": "^25.0.8",
+    "typescript": "^5.9.3"
+  }
+}

package/src/apply.ts

@@ -0,0 +1,59 @@
+import path from 'node:path'
+import { promises as fs } from 'node:fs'
+import type { PromptslotConfig } from './config'
+
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const buildBlock = (value: string, markers: PromptslotConfig['markers']) => {
+  const trimmed = value.replace(/\s+$/, '')
+  return `${markers.start}\n${trimmed}\n${markers.end}`
+}
+
+const replaceInContent = (
+  content: string,
+  value: string,
+  config: PromptslotConfig,
+) => {
+  const block = buildBlock(value, config.markers)
+  const start = escapeRegExp(config.markers.start)
+  const end = escapeRegExp(config.markers.end)
+  const blockRegex = new RegExp(`${start}[\\s\\S]*?${end}`, 'g')
+
+  if (blockRegex.test(content)) {
+    const next = content.replace(blockRegex, block)
+    return { next, changed: next !== content }
+  }
+
+  if (content.includes(config.placeholder)) {
+    const next = content.split(config.placeholder).join(block)
+    return { next, changed: next !== content }
+  }
+
+  return { next: content, changed: false }
+}
+
+const fileExists = async (filePath: string) =>
+  fs.access(filePath).then(() => true).catch(() => false)
+
+export const applyToFiles = async (
+  targets: string[],
+  value: string,
+  config: PromptslotConfig,
+) => {
+  const changedFiles: string[] = []
+
+  for (const target of targets) {
+    const resolved = path.resolve(target)
+    const exists = await fileExists(resolved)
+    if (!exists) continue
+
+    const content = await fs.readFile(resolved, 'utf8')
+    const { next, changed } = replaceInContent(content, value, config)
+    if (!changed) continue
+
+    await fs.writeFile(resolved, next)
+    changedFiles.push(target)
+  }
+
+  return changedFiles
+}

package/src/cli-name.ts

@@ -0,0 +1,13 @@
+import dotenv from 'dotenv'
+
+dotenv.config({ quiet: true })
+
+const DEFAULT_CLI_NAME = 'pmt'
+
+export const getCliName = () => {
+  const envName = process.env.CLI_NAME?.trim()
+  if (envName) return envName
+  return DEFAULT_CLI_NAME
+}
+
+export const formatCommand = (command: string) => `${getCliName()} ${command}`

package/src/cli.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+import { Command } from 'commander'
+import { getCliName } from './cli-name'
+import { initCompletion } from './completion'
+import { registerCommands } from './commands'
+import { autoRepairLinks } from './link-repair'
+
+const program = new Command()
+
+program
+  .name(getCliName())
+  .description('占位符 prompt 管理 CLI')
+  .helpOption('-h, --help', '显示帮助')
+  .version('0.1.0', '-v, --version', '显示版本')
+
+registerCommands(program)
+initCompletion()
+
+const args = process.argv.slice(2)
+if (!args.length) {
+  program.outputHelp()
+  process.exit(0)
+}
+
+if (args.length === 1 && (args[0] === '-h' || args[0] === '--help')) {
+  program.outputHelp()
+  process.exit(0)
+}
+
+await autoRepairLinks()
+await program.parseAsync(process.argv)

package/src/command-apply.ts

@@ -0,0 +1,84 @@
+import { promises as fs } from 'node:fs'
+import { applyToFiles } from './apply'
+import { formatCommand } from './cli-name'
+import { readSourceText } from './content-source'
+import { loadMergedConfig } from './config'
+import { fileExists, isUrl, resolvePath, resolveTargets } from './helpers'
+
+const log = (text: string) => console.log(text)
+const fail = (text: string) => {
+  console.error(text)
+  process.exitCode = 1
+}
+
+const requireMergedConfig = async () => {
+  const merged = await loadMergedConfig()
+  if (!merged.hasConfig) {
+    fail(`未找到配置文件，请先运行: ${formatCommand('init')}`)
+    return null
+  }
+  return merged
+}
+
+export const insertPlaceholder = async (target?: string) => {
+  if (!target) {
+    fail(`用法: ${formatCommand('insert <file>')}`)
+    return
+  }
+
+  const merged = await requireMergedConfig()
+  if (!merged) return
+
+  const resolved = resolvePath(target)
+  const exists = await fileExists(resolved)
+  if (!exists) {
+    fail(`文件不存在: ${resolved}`)
+    return
+  }
+
+  const content = await fs.readFile(resolved, 'utf8')
+  if (content.includes(merged.config.placeholder)) {
+    log('文件已包含占位符')
+    return
+  }
+
+  const next = content.replace(/\s*$/, `\n${merged.config.placeholder}\n`)
+  await fs.writeFile(resolved, next)
+  log(`已插入占位符: ${target}`)
+}
+
+export const applyCurrent = async (targets: string[]) => {
+  const merged = await requireMergedConfig()
+  if (!merged) return
+
+  const current = merged.config.current
+  if (!current) {
+    fail(`未设置当前值，请先运行: ${formatCommand('set <name> <file>')}`)
+    return
+  }
+
+  const sourcePath = merged.resolvedSources[current]
+  if (!sourcePath) {
+    fail(`当前值未配置路径: ${current}`)
+    return
+  }
+
+  if (!isUrl(sourcePath)) {
+    const sourceExists = await fileExists(sourcePath)
+    if (!sourceExists) {
+      fail(`当前文件不存在: ${sourcePath}`)
+      return
+    }
+  }
+
+  const value = await readSourceText(sourcePath)
+  const allTargets = await resolveTargets(targets, Object.values(merged.resolvedSources))
+  const changed = await applyToFiles(allTargets, value, merged.config)
+
+  if (!changed.length) {
+    log('未找到需要替换的文件')
+    return
+  }
+
+  log(`已更新 ${changed.length} 个文件`)
+}

package/src/command-completion.ts

@@ -0,0 +1,31 @@
+import { cleanupCompletion, installCompletion } from './completion'
+import { formatCommand } from './cli-name'
+
+const fail = (text: string) => {
+  console.error(text)
+  process.exitCode = 1
+}
+
+export const completionInstall = async () => {
+  try {
+    installCompletion()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    fail(`自动安装失败: ${message}`)
+    fail(`可手动执行: ${formatCommand('completion show')}`)
+  }
+}
+
+export const completionCleanup = async () => {
+  try {
+    cleanupCompletion()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    fail(`自动卸载失败: ${message}`)
+  }
+}
+
+export const completionShow = async () => {
+  process.stdout.write(`${formatCommand('--completion')}\n`)
+  process.stdout.write(`${formatCommand('--completion-fish')}\n`)
+}