@hagicode/hagi18n 0.1.0-dev.1.1.45d0d2f → 0.1.0-dev.3.1.5b3b044

package/README.md

@@ -9,6 +9,19 @@ It supports:
 - Safe `sync` and `prune` mutations with dry-run defaults.
 - Optional `hagi18n.yaml` defaults so each project can define its own locale layout.
 
+## AI Skill
+
+This repository now ships a local Codex-style skill at [`skills/hagi18n/SKILL.md`](skills/hagi18n/SKILL.md).
+
+Use it when an AI agent needs to:
+
+- run or explain `hagi18n audit`, `doctor`, `sync`, or `prune`
+- add or review a `hagi18n.yaml` file
+- inspect or modify the source in `repos/hagi18n`
+- validate locale maintenance workflows against a consumer repository
+
+The skill includes focused references for command usage, configuration, and package development.
+
 ## Requirements
 
 - Node.js 20 or newer

package/README_cn.md

@@ -9,6 +9,19 @@
 - 安全的 `sync` / `prune` 变更流程，默认 dry-run
 - 可选的 `hagi18n.yaml` 项目配置，适配不同仓库目录结构
 
+## AI Skill
+
+仓库现在内置了一套本地 Codex 风格 skill，位置在 [`skills/hagi18n/SKILL.md`](skills/hagi18n/SKILL.md)。
+
+当 AI 代理需要完成以下任务时，可以直接使用这套 skill：
+
+- 执行或解释 `hagi18n audit`、`doctor`、`sync`、`prune`
+- 新增或审查 `hagi18n.yaml`
+- 检查或修改 `repos/hagi18n` 内源码
+- 在消费方仓库中验证语言包维护流程
+
+skill 内还附带了命令使用、配置结构和包开发流程的拆分参考文档。
+
 ## 前提
 
 - Node.js 20 或更高版本

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagi18n",
-  "version": "0.1.0-dev.1.1.45d0d2f",
+  "version": "0.1.0-dev.3.1.5b3b044",
   "description": "Scoped npm package foundation for HagiCode internationalization tooling.",
   "homepage": "https://github.com/HagiCode-org/hagi18n#readme",
   "bugs": {
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "README_cn.md"
   ],

package/skills/hagi18n/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: hagi18n
+description: Use when the user wants to audit, doctor, sync, prune, configure, or modify YAML locale maintenance workflows powered by @hagicode/hagi18n, including package usage in other repositories and source changes in repos/hagi18n.
+---
+
+# Hagi18n
+
+Use this skill when the task is to:
+
+- run or explain the `hagi18n` CLI
+- add, review, or fix a `hagi18n.yaml` configuration
+- inspect locale drift, placeholder mismatches, or legacy locale references
+- modify `@hagicode/hagi18n` source, tests, or release packaging in `repos/hagi18n`
+
+## Core rules
+
+- Prefer package-first usage for consumer repositories: `npx @hagicode/hagi18n <command>` or the installed `hagi18n` binary.
+- Run build, test, and development commands with the working directory set to `repos/hagi18n`.
+- `sync` and `prune` are dry-run by default. Only add `--write` when the user explicitly wants file mutations.
+- Prefer canonical locale names such as `en-US` and `zh-CN`; aliases like `en`, `en-us`, `zh`, and `zh-cn` are normalized by the toolkit, but new code and docs should use canonical names.
+- Use this package for locale maintenance and repository hygiene. Do not treat it as a runtime translation loader or UI i18n framework.
+
+## Choose the workflow
+
+1. Command usage in a consumer repository -> read [`references/cli-workflows.md`](references/cli-workflows.md)
+2. Locale layout, config shape, or doctor scan behavior -> read [`references/config-and-layout.md`](references/config-and-layout.md)
+3. Source changes, tests, or package validation in `repos/hagi18n` -> read [`references/development-and-validation.md`](references/development-and-validation.md)
+
+## Source of truth
+
+- CLI entry point: `src/cli.ts`
+- Config loading and default rules: `src/config.ts`
+- Audit, doctor, sync, and prune behavior: `src/locale-toolkit.ts`
+
+## References
+
+- [`references/cli-workflows.md`](references/cli-workflows.md) - package usage, command intent, exit code expectations, and mutation safety
+- [`references/config-and-layout.md`](references/config-and-layout.md) - supported locale tree layout, `hagi18n.yaml` shape, aliases, and doctor defaults
+- [`references/development-and-validation.md`](references/development-and-validation.md) - repository-local scripts, source map, and expected validation after edits

package/skills/hagi18n/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Hagi18n"
+  short_description: "Operate and modify the HagiCode YAML locale maintenance toolkit."
+  default_prompt: "Use $hagi18n to inspect, run, configure, or update the locale maintenance toolkit in repos/hagi18n."
+
+policy:
+  allow_implicit_invocation: true

package/skills/hagi18n/references/cli-workflows.md

@@ -0,0 +1,62 @@
+# CLI Workflows
+
+## Use cases
+
+Use `@hagicode/hagi18n` when a repository stores locale files as YAML trees and needs a maintenance workflow instead of ad hoc scripts.
+
+Common goals:
+
+- audit locale drift against a canonical base locale
+- scan the repository for legacy locale references
+- fill in missing files or keys safely
+- prune files or keys that no longer exist in the base locale
+
+## Preferred invocation
+
+In a consumer repository:
+
+```bash
+npx @hagicode/hagi18n audit --config hagi18n.yaml
+```
+
+If the package is already installed:
+
+```bash
+hagi18n doctor --config hagi18n.yaml
+```
+
+For development against the local source tree in `repos/hagi18n`:
+
+```bash
+cd repos/hagi18n
+npm run dev -- audit --locales-root ../some-app/src/locales --base-locale en-US
+```
+
+## Command intent
+
+- `info`: print package metadata and foundation status
+- `audit`: compare locale files against a base locale and report drift
+- `report`: run the audit flow and always print JSON
+- `doctor`: run the audit flow and scan text files for legacy locale references
+- `sync`: add missing files and keys from the base locale
+- `prune`: remove files and keys that no longer exist in the base locale
+
+## Mutation safety
+
+- `sync` and `prune` default to dry-run behavior.
+- Add `--write` only when the user clearly wants files changed.
+- `--dry-run` wins over `--write` if both are present.
+- `--to` can be repeated to limit mutations to specific target locales.
+
+## Exit code expectations
+
+- `audit`: `0` when clean, `1` when issues exist
+- `report`: same behavior as `audit`, but always JSON
+- `doctor`: `1` when audit issues or legacy reference issues exist
+- `sync` and `prune`: `1` for parse or processing errors; planned or applied mutations still produce a structured summary
+
+## Working assumptions
+
+- The toolkit expects a base locale such as `en-US`.
+- Locale aliases are accepted, but output and new config should prefer canonical locale names.
+- JSON mode is appropriate when another tool or agent needs machine-readable results.

package/skills/hagi18n/references/config-and-layout.md

@@ -0,0 +1,116 @@
+# Config And Layout
+
+## Expected locale tree
+
+The package works on a locale root containing per-locale directories:
+
+```text
+src/locales/
+  en-US/
+    common.yml
+    features/editor.yml
+  zh-CN/
+    common.yml
+    features/editor.yml
+```
+
+Supported files:
+
+- `.yml`
+- `.yaml`
+
+Supported documents:
+
+- top-level YAML mappings only
+- nested objects
+- arrays
+- scalar translation leaves
+- `{{placeholder}}` interpolation tokens
+
+## Locale normalization
+
+The toolkit currently normalizes these aliases:
+
+- `en`, `en-us` -> `en-US`
+- `zh`, `zh-cn` -> `zh-CN`
+
+Prefer canonical values in code, tests, and docs even though aliases resolve correctly.
+
+## Config file
+
+By default the CLI looks for `hagi18n.yaml` or `hagi18n.yml` in the current working directory. Relative paths are resolved from the config file directory.
+
+Minimal example:
+
+```yaml
+localesRoot: src/locales
+repoRoot: .
+baseLocale: en-US
+targetLocales:
+  - zh-CN
+```
+
+Extended example:
+
+```yaml
+localesRoot: src/locales
+repoRoot: .
+baseLocale: en-US
+targetLocales:
+  - zh-CN
+doctor:
+  excludedDirectories:
+    - .git
+    - dist
+    - node_modules
+  textFileExtensions:
+    - .ts
+    - .tsx
+    - .js
+    - .md
+  excludedPathPrefixes:
+    - src/generated/
+  allowlist:
+    legacy-language-change-call:
+      - src/legacy-test.ts
+```
+
+## Config precedence
+
+1. CLI flags or direct API options
+2. `hagi18n.yaml` or `hagi18n.yml`
+3. package defaults
+
+## Current doctor defaults
+
+Default excluded directories:
+
+- `.git`
+- `coverage`
+- `dist`
+- `indexGenerator`
+- `node_modules`
+- `public`
+
+Default text file extensions:
+
+- `.cjs`
+- `.js`
+- `.jsx`
+- `.md`
+- `.mjs`
+- `.ts`
+- `.tsx`
+
+Default excluded path prefixes:
+
+- `src/generated/`
+
+Default built-in scan rules look for:
+
+- legacy `src/locales/en/` style paths
+- `changeLanguage("en")` style canonical language switches
+- `language: "en"` style canonical language literals
+- `'en' | 'zh-CN'` style unions and casts
+
+When the user needs exact behavior, inspect `src/config.ts` and use that file as the source of truth.

package/skills/hagi18n/references/development-and-validation.md

@@ -0,0 +1,50 @@
+# Development And Validation
+
+## Repository-local commands
+
+Run these from `repos/hagi18n`:
+
+```bash
+npm test
+npm run build
+npm run lint
+npm run pack:check
+```
+
+Useful package maintenance helpers:
+
+```bash
+npm run publish:check-prereqs
+npm run publish:prepare-dev-version
+npm run publish:verify-release
+```
+
+## Source map
+
+- `src/cli.ts`: command registration, option parsing, summary output, and exit code wiring
+- `src/config.ts`: config discovery, YAML parsing, defaults, doctor rules, and config resolution
+- `src/locale-toolkit.ts`: file walking, YAML reads, placeholder checks, doctor scanning, and mutation planning
+- `src/index.ts`: public exports for API consumers
+- `src/__tests__/`: CLI, config, index, and locale toolkit coverage
+
+## Packaging notes
+
+- Published files are controlled by `package.json`.
+- When adding AI-facing skill content or other runtime-relevant docs, keep package contents aligned with the `files` allowlist.
+- The package is ESM and exports the CLI binary from `dist/cli.js`.
+
+## Validation expectations after edits
+
+- Run the narrowest relevant tests first if the change is isolated.
+- Run `npm test` after source or skill-related packaging changes.
+- Run `npm run build` after TypeScript or export changes.
+- Run `npm run pack:check` when package contents or publish-facing files change.
+
+## Behavior references
+
+The package preserves the Web maintenance model:
+
+- `repos/web/buildTools/lib/i18nLocaleToolkit.mjs` -> `src/locale-toolkit.ts`
+- `repos/web/buildTools/i18n-locale-cli.mjs` -> `src/cli.ts`
+
+Use the local source tree as the writable source of truth and treat the Web mapping as historical context only.