@doki-land/nifty-skills 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,50 @@
1
+ # `@doki-land/nifty-skills`
2
+
3
+ [Agent Skills](https://agentskills.io/specification) for [**Nifty**](https://www.npmjs.com/package/@doki-land/nifty) — gitmoji commit conventions, hybrid Cargo + npm release workflows, and gix-backed git history tools.
4
+
5
+ This package is **docs-only**. It teaches agents how to invoke the published `nifty` CLI. It does not replace `@doki-land/nifty` or its native bindings.
6
+
7
+ ## Install
8
+
9
+ Install one skill into a project (requires Node.js 18+):
10
+
11
+ ```bash
12
+ npx skills add @doki-land/nifty-skills --skill nifty -y
13
+ ```
14
+
15
+ List available skills or install globally:
16
+
17
+ ```bash
18
+ npx skills add @doki-land/nifty-skills --list
19
+ npx skills add @doki-land/nifty-skills --skill nifty-release -y -g
20
+ ```
21
+
22
+ ## Skills
23
+
24
+ | Skill | Load when |
25
+ | --- | --- |
26
+ | `nifty` | User mentions Nifty tooling, hybrid monorepos, or you need the command map |
27
+ | `nifty-commit` | Gitmoji commit lint, subject format, `nifty lint` / `nifty check` |
28
+ | `nifty-release` | `nifty bump`, `publish`, `trust`, `upload`, `change-logs`, CI release |
29
+ | `nifty-git-history` | `nifty reword`, `nifty retime`, object-layer history rewrite |
30
+
31
+ ## Prerequisites
32
+
33
+ Consumers need the CLI:
34
+
35
+ ```bash
36
+ npm install @doki-land/nifty
37
+ nifty --help
38
+ ```
39
+
40
+ Monorepo authors can use `pnpm exec nifty` after `pnpm install` in [npm-tools](https://github.com/oovm/npm-tools).
41
+
42
+ ## Links
43
+
44
+ - [npm package](https://www.npmjs.com/package/@doki-land/nifty-skills)
45
+ - [Nifty CLI](https://www.npmjs.com/package/@doki-land/nifty)
46
+ - [Source](https://github.com/oovm/npm-tools/tree/dev/projects/packages/nifty-skills)
47
+
48
+ ## License
49
+
50
+ [MPL-2.0](https://www.npmjs.com/package/@doki-land/nifty-skills?activeTab=code)
package/package.json ADDED
@@ -0,0 +1,26 @@
1
+ {
2
+ "bugs": {
3
+ "url": "https://github.com/oovm/npm-tools/issues"
4
+ },
5
+ "description": "Agent Skills for Nifty gitmoji commits, npm release, and git history tooling",
6
+ "files": [
7
+ "skills",
8
+ "README.md"
9
+ ],
10
+ "homepage": "https://github.com/oovm/npm-tools/tree/dev/projects/packages/nifty-skills#readme",
11
+ "license": "MPL-2.0",
12
+ "name": "@doki-land/nifty-skills",
13
+ "publishConfig": {
14
+ "access": "public"
15
+ },
16
+ "repository": {
17
+ "directory": "projects/packages/nifty-skills",
18
+ "type": "git",
19
+ "url": "git+https://github.com/oovm/npm-tools.git"
20
+ },
21
+ "scripts": {
22
+ "typecheck": "node -e \"console.log('docs-only skill package')\""
23
+ },
24
+ "type": "module",
25
+ "version": "0.0.2"
26
+ }
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: nifty
3
+ description: >-
4
+ Orchestrate Nifty CLI workflows for gitmoji commits, hybrid Cargo + npm release,
5
+ and gix-backed git history tools. Load when the user mentions nifty, @doki-land/nifty,
6
+ gitmoji release tooling, or npm-tools monorepo helpers.
7
+ ---
8
+
9
+ # Nifty
10
+
11
+ [Nifty](https://www.npmjs.com/package/@doki-land/nifty) is gitmoji-first release tooling for hybrid **Cargo + npm** workspaces. Native git work uses **gix** (Rust). Changelog tag ranges use the `git` CLI.
12
+
13
+ ## Before you act
14
+
15
+ 1. Confirm `@doki-land/nifty` is installed (`nifty --help`) or use `pnpm exec nifty` in the npm-tools repo.
16
+ 2. Look for `nifty.config.ts` at the project root (`defineConfig`, `authorMap`, `publish.packages`, `changelog.*`).
17
+ 3. Load a focused sub-skill when the task is narrow (see table below).
18
+
19
+ ## Sub-skills
20
+
21
+ | Task | Skill |
22
+ | --- | --- |
23
+ | Commit subject lint, gitmoji rules | `nifty-commit` |
24
+ | Version bump, npm publish/trust, GitHub upload, reference changelogs | `nifty-release` |
25
+ | Object-layer reword/retime | `nifty-git-history` |
26
+
27
+ ## Command map
28
+
29
+ | Command | Purpose |
30
+ | --- | --- |
31
+ | `nifty lint` / `nifty check` | Gitmoji commit subject rules |
32
+ | `nifty bump` | Align crate + package versions |
33
+ | `nifty publish` | Publish workspace npm packages (OIDC or token + TOTP) |
34
+ | `nifty trust` | Configure npm Trusted Publisher |
35
+ | `nifty update` | Bump Cargo and npm dependencies |
36
+ | `nifty upload` | GitHub Release assets or GitHub Pages |
37
+ | `nifty install-native` | Stage CI `.node` artifacts into platform packages |
38
+ | `nifty reword` | Rewrite commit messages at the object layer |
39
+ | `nifty retime` | Spread timestamps on a new branch |
40
+ | `nifty change-logs` | Draft release reference changelogs from tags |
41
+
42
+ Global flag: `-C, --cwd <dir>`.
43
+
44
+ ## Layout (npm-tools monorepo)
45
+
46
+ ```text
47
+ projects/crates/ # Rust libraries + nifty-napi
48
+ projects/packages/ # @doki-land/nifty + platform @doki-land/nifty-*
49
+ scripts/ci/ # publish-npm.mjs, nifty.mjs
50
+ ```
51
+
52
+ Do **not** confuse npm-tools `legion` / Valkyrie with Nifty. Nifty is independent Node-API + TypeScript CLI tooling.
53
+
54
+ ## Agent discipline
55
+
56
+ - Prefer **`nifty` CLI** over reimplementing git/npm steps in ad-hoc scripts.
57
+ - Run **`nifty check`** or **`nifty lint --from … --to …`** before claiming commit history is clean.
58
+ - For publish/trust, follow **`nifty-release`**: `nifty publish` skips registry versions that already exist. Run **`nifty trust`** after the first publish of any new package name.
59
+ - Object-layer rewrite (**reword/retime**) rewrites history — warn the user and require explicit `--dry-run` first when appropriate.
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: nifty-commit
3
+ description: >-
4
+ Lint and enforce Nifty gitmoji commit conventions with nifty lint and nifty check.
5
+ Load when fixing commit subjects, gitmoji format, or pre-release commit hygiene.
6
+ ---
7
+
8
+ # Nifty commit conventions
9
+
10
+ ## Subject shape
11
+
12
+ Every commit **subject** (first line) must:
13
+
14
+ 1. Start with a **known gitmoji** immediately followed by a **space**
15
+ 2. Use an **English** imperative phrase after the gitmoji (project convention for publish repos)
16
+ 3. Match `gitmoji + body` formatting rules enforced by `nifty lint`
17
+
18
+ Known gitmojis (Nifty default set):
19
+
20
+ ```text
21
+ ✨ 🎨 🚀 🐛 🚑 🔥 💥 ♻️ 🔧 📝 👷 🧹 ⬆️ 🧪 🔨 📦
22
+ ```
23
+
24
+ ## Commands
25
+
26
+ ```bash
27
+ # Lint subjects in a ref range (default to..HEAD)
28
+ nifty lint --from v0.0.1 --to HEAD
29
+
30
+ # Lint explicit strings
31
+ nifty lint --subject "✨ Add feature"
32
+
33
+ # Fail on errors (CI gate)
34
+ nifty check --from origin/dev..HEAD
35
+ ```
36
+
37
+ ## Rules (nifty-linter)
38
+
39
+ | Rule | Default | Meaning |
40
+ | --- | --- | --- |
41
+ | `gitmoji/subject` | error | Subject must start with gitmoji + space |
42
+ | `gitmoji/known` | error | Gitmoji must be in the known list |
43
+ | `gitmoji/body` | warning | Text after gitmoji must not be empty |
44
+ | `gitmoji/format` | warning | Subject should match canonical formatting |
45
+
46
+ ## Commit message style (when you write commits)
47
+
48
+ Align with Nifty/npm-tools git policy when the user asks you to commit:
49
+
50
+ - Subject starts with one real gitmoji character
51
+ - Subject and body in **English**
52
+ - No Conventional Commit prefix (`feat:`, `fix:`) instead of gitmoji
53
+ - Wrap identifiers in backticks: `` `nifty-skills` ``, `` `publish-npm.mjs` ``
54
+ - No semicolons in commit messages
55
+ - One gitmoji at the start of the subject only
56
+
57
+ ## Workflow
58
+
59
+ 1. Run `nifty lint` on the range about to merge or release.
60
+ 2. Fix subjects locally or plan a **`nifty reword`** pass (see `nifty-git-history`) for history already pushed.
61
+ 3. Re-run `nifty check` until exit code is 0.
62
+
63
+ Do not bypass lint with custom regex when `nifty lint` is available.
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: nifty-git-history
3
+ description: >-
4
+ Object-layer git history tools: nifty reword and nifty retime without interactive rebase.
5
+ Load when rewriting commit messages or timestamps while preserving author identity.
6
+ ---
7
+
8
+ # Nifty git history
9
+
10
+ Implemented in `nifty-history` (gix). **Author and committer name/email are never replaced** with local `user.name` / `user.email` — only messages or timestamps change (plus parent relinking when ancestors rewrite).
11
+
12
+ Warn the user before rewriting shared branches. Prefer `--dry-run` first.
13
+
14
+ ## Reword
15
+
16
+ Export JSON map, preview, apply:
17
+
18
+ ```bash
19
+ nifty reword export --base 34e1e665^ --ref dev --path reword.pending.json
20
+ nifty reword rewrite --base 34e1e665^ --ref dev --path reword.pending.json --dry-run
21
+ nifty reword rewrite --base 34e1e665^ --ref dev --path reword.pending.json
22
+ ```
23
+
24
+ ### Map format
25
+
26
+ Document shape:
27
+
28
+ ```json
29
+ {
30
+ "version": 1,
31
+ "entries": [
32
+ { "hash": "abc123…", "message": "✨ Subject\n\nBody." }
33
+ ]
34
+ }
35
+ ```
36
+
37
+ Flat `{ "abc12345": "message" }` is also accepted.
38
+
39
+ Hash prefixes must be **unique** within the rewrite range.
40
+
41
+ ## Retime
42
+
43
+ Spread author and committer timestamps across a window. Writes a **new branch** (default `time-travel`); current branch unchanged.
44
+
45
+ Range mode — commits in `(commit..tip]`:
46
+
47
+ ```bash
48
+ nifty retime 2a990148
49
+ nifty retime 2a990148 --start-date 2019-01-01 --end-date 2019-06-01 --branch dev-time-travel
50
+ nifty retime 2a990148 -s 2019-03-22T09:00:00 --tip HEAD
51
+ ```
52
+
53
+ Root mode — all commits from repository root through `tip`:
54
+
55
+ ```bash
56
+ nifty retime root
57
+ nifty retime root -s 2019-01-01 --message "🎂 Project initialized!" --branch time-travel
58
+ ```
59
+
60
+ Datetime: `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`. End defaults to `start + N days` where `N` is commit count in range.
61
+
62
+ ## Change logs (tag ranges)
63
+
64
+ For release reference drafts, use **`nifty-release`** (`nifty change-logs`). That command uses `git log` for tag ranges; reword/retime use gix object writes.
65
+
66
+ ## Safety
67
+
68
+ | Do | Do not |
69
+ | --- | --- |
70
+ | `--dry-run` before `reword rewrite` | Force-push without user consent |
71
+ | Explicit `--ref` when HEAD is detached | Use `git rebase -i` when user asked for Nifty tools |
72
+ | Explain parent relink-only rows in dry-run | Amend commits with `git commit --amend` for bulk history fixes |
73
+
74
+ After rewrite, the user must force-update the target ref if it was already published.
@@ -0,0 +1,106 @@
1
+ ---
2
+ name: nifty-release
3
+ description: >-
4
+ Nifty release workflow: bump, publish, trust, upload, change-logs, and install-native.
5
+ Load when cutting versions, npm OIDC publish, Trusted Publisher, or GitHub Release assets.
6
+ ---
7
+
8
+ # Nifty release
9
+
10
+ ## Configuration
11
+
12
+ Create or extend `nifty.config.ts`:
13
+
14
+ ```ts
15
+ export default {
16
+ githubToken: process.env.GITHUB_TOKEN,
17
+ authorMap: { "you@example.com": { login: "handle", id: 12345 } },
18
+ changelog: {
19
+ authorMap: "documentation/maintenance/author-github.json",
20
+ releasesDir: "documentation/maintenance/releases",
21
+ repo: "owner/name",
22
+ },
23
+ publish: {
24
+ packages: ["@scope/app", "@scope/app-native"],
25
+ },
26
+ };
27
+ ```
28
+
29
+ `publish.packages` lists every package name for **`nifty trust`**, including registry-only native sidecars.
30
+
31
+ ## Version bump
32
+
33
+ ```bash
34
+ nifty bump # patch
35
+ nifty bump minor
36
+ nifty bump --version 0.0.3
37
+ nifty bump --dry-run
38
+ ```
39
+
40
+ Aligns all `projects/crates/*/Cargo.toml` and `projects/packages/*/package.json` versions.
41
+
42
+ ## npm publish and trust
43
+
44
+ **Default: publish the whole workspace.** Nifty walks packages in dependency order and **skips versions already on the registry** (cache + `npm view`). After a release you can run plain `nifty publish` again — only new or bumped packages are uploaded.
45
+
46
+ ```bash
47
+ nifty publish --dry-run
48
+ nifty publish --access public
49
+ nifty trust --dry-run
50
+ nifty trust
51
+ ```
52
+
53
+ Optional subset (new package only, or retry one failure):
54
+
55
+ ```bash
56
+ nifty publish --package @doki-land/nifty-skills
57
+ nifty trust --only @doki-land/nifty-skills
58
+ ```
59
+
60
+ **First publish of a new package name** (e.g. `@doki-land/nifty-skills`): run **`nifty trust`** after `nifty publish` so GitHub Actions OIDC can publish on the next tag. `nifty trust` uses `publish.packages` from `nifty.config.ts` when set, otherwise all non-private workspace packages.
61
+
62
+ Local auth: `NPM_TOKEN`, `--npm-token`, `--otp`, or `--totp-secret` (see `nifty publish --help`). Trust live configuration requires OTP/TOTP.
63
+
64
+ **npm-tools CI**: tag `vX.Y.Z` triggers `.github/workflows/publish-npm.yml` → `scripts/ci/publish-npm.mjs` (OIDC, no long-lived token in YAML). Native `.node` files ship as `@doki-land/nifty-*` optional packages, not GitHub Release assets.
65
+
66
+ ## Reference changelogs
67
+
68
+ Output is a **draft index** for hand-editing release notes — not the published GitHub Release body.
69
+
70
+ ```bash
71
+ nifty change-logs --version 0.0.3
72
+ nifty change-logs --from v0.0.2 --to v0.0.3
73
+ nifty change-logs --version 0.0.3 --write
74
+ nifty change-logs --tags
75
+ nifty change-logs lookup --email you@example.com --fetch
76
+ ```
77
+
78
+ Default paths: `documentation/maintenance/author-github.json`, `documentation/maintenance/releases/vX.Y.Z.reference.md`.
79
+
80
+ ## GitHub upload
81
+
82
+ ```bash
83
+ nifty upload --release --dir dist --tag v0.0.3 --token "$GITHUB_TOKEN"
84
+ nifty upload --pages --dir dist
85
+ nifty upload --both --dir dist --github-action
86
+ ```
87
+
88
+ Platform `.node` binaries are **not** uploaded here — they publish via `nifty publish` / CI matrix.
89
+
90
+ ## CI native staging (maintainers)
91
+
92
+ ```bash
93
+ nifty install-native --from-artifacts path/to/native-artifacts
94
+ ```
95
+
96
+ Then `nifty publish` includes staged `@doki-land/nifty-<platform>` packages.
97
+
98
+ ## Release checklist
99
+
100
+ 1. `nifty check` on commits since last tag
101
+ 2. `nifty bump` (or explicit version)
102
+ 3. Commit version bump, tag `vX.Y.Z`, push branch + tag
103
+ 4. `nifty publish` (skips packages already at that version on npm) — or let CI publish on tag
104
+ 5. **`nifty trust`** for any **new** package name not yet on the Trusted Publisher list
105
+ 6. `nifty change-logs --version X.Y.Z --write` for reference draft
106
+ 7. `nifty upload --release …` when generic assets need GitHub Release upload