pakem-cli 1.2.1 → 1.3.0

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/CHANGELOG.md CHANGED
@@ -1,7 +1,16 @@
1
+ ## 1.3.0 — 2026-11-17
2
+
3
+ ### Added
4
+ - Interactive `npx pakem-cli` installer: in a terminal it asks where the skill should live (Claude Code global, agents/skills.sh global, current project, or a custom path), confirms replacement, and reports the installed Python version. Without a TTY, or with `--yes`/`--dir`/`--project`, it keeps the non-interactive path so agents and CI can call it safely.
5
+ - The npm package declares `@clack/prompts` as its only runtime dependency, used by the installer. The Python CLI/Core remains standard-library only.
6
+
7
+ ### Changed
8
+ - Version 1.3.0 across the CLI, `SKILL.md`, MCP `serverInfo`, and the npm package.
9
+
1
10
  ## 1.2.1 — 2026-11-17
2
11
 
3
12
  ### Added
4
- - `npx pakem` installer (npm package `pakem`): copies the skill into `~/.claude/skills/pakem` (or `--project` for `./.claude/skills/pakem`, or `--dir` for another skills folder), then delegates any other argument to the bundled Python CLI (`npx pakem init --type app`). The package ships `SKILL.md`, scripts, schemas, references, and assets; it adds no npm dependency to the target project. `npm pack` refuses to build when `package.json` and `scripts/pakem.py` versions differ, and `tests/test_docs.py` guards the same invariant.
13
+ - `npx pakem-cli` installer (npm package `pakem-cli`): copies the skill into `~/.claude/skills/pakem` (or `--project` for `./.claude/skills/pakem`, or `--dir` for another skills folder), then delegates any other argument to the bundled Python CLI (`npx pakem-cli init --type app`). The package ships `SKILL.md`, scripts, schemas, references, and assets; it adds no npm dependency to the target project. `npm pack` refuses to build when `package.json` and `scripts/pakem.py` versions differ, and `tests/test_docs.py` guards the same invariant.
5
14
 
6
15
  ### Fixed
7
16
  - Gate `scope` compared only the working tree (`git diff HEAD`), so an agent that committed its work and then ran `check`/`finish` passed without ever being compared against plan scope. The gate now anchors on the HEAD recorded when the session started (`.pakem/sessions/*.json` → `git.head`) and diffs that commit against the working tree in one pass: commits made during the session, uncommitted edits, and untracked files all count. Without an active session it falls back to `git diff HEAD`, so CI on a clean checkout still needs an explicit base to mean anything.
package/README-ID.md CHANGED
@@ -84,15 +84,16 @@ Pakem bikin kerja agent **konsisten** 🌙, **bisa dilanjut** 🔁, dan **bisa d
84
84
 
85
85
  Folder ini adalah sebuah skill. Taruh sebagai `pakem/` di folder skill agent kamu (mis. `.claude/skills/pakem/` atau `~/.claude/skills/pakem/`). Untuk agent lain, cukup jalankan CLI-nya langsung.
86
86
 
87
- Dengan Node 18+, paket npm memasang skill-nya untuk kamu (Pakem sendiri tetap butuh Python 3.10+):
87
+ Dengan Node 18+, paket npm memasang skill-nya untuk kamu (Pakem sendiri tetap butuh Python 3.10+). Di terminal ia membuka picker; flag membuatnya non-interaktif:
88
88
 
89
89
  ```bash
90
- npx pakem # ~/.claude/skills/pakem
91
- npx pakem install --project # ./.claude/skills/pakem
92
- npx pakem install --dir ~/.agents/skills/pakem
90
+ npx pakem-cli # interactive picker
91
+ npx pakem-cli install --yes # non-interactive, global default
92
+ npx pakem-cli install --project # ./.claude/skills/pakem
93
+ npx pakem-cli install --dir ~/.agents/skills/pakem
93
94
  ```
94
95
 
95
- Paket ini hanya menyalin skill; tidak menambah dependency npm ke proyekmu. Argumen lain diteruskan ke CLI Python bawaan paket (`npx pakem init --type app`).
96
+ Paket ini hanya menyalin skill; tidak menambah dependency npm ke proyekmu. Argumen lain diteruskan ke CLI Python bawaan paket (`npx pakem-cli init --type app`).
96
97
 
97
98
  Butuh **Python 3.10+**. CLI/Core dasar hanya memakai standard library. Operasi identitas Ed25519 opsional dan memerlukan `python -m pip install cryptography`.
98
99
 
package/README.md CHANGED
@@ -84,15 +84,16 @@ Pakem makes agent work **consistent** 🌙, **resumable** 🔁, and **provably f
84
84
 
85
85
  This folder is a skill. Put it in as `pakem/` inside your agent's skills folder (e.g. `.claude/skills/pakem/` or `~/.claude/skills/pakem/`). For other agents, just run the CLI directly.
86
86
 
87
- With Node 18+, the npm package installs the skill for you (Pakem itself still runs on Python 3.10+):
87
+ With Node 18+, the npm package installs the skill for you (Pakem itself still runs on Python 3.10+). In a terminal it opens a picker; flags keep it non-interactive:
88
88
 
89
89
  ```bash
90
- npx pakem # ~/.claude/skills/pakem
91
- npx pakem install --project # ./.claude/skills/pakem
92
- npx pakem install --dir ~/.agents/skills/pakem
90
+ npx pakem-cli # interactive picker
91
+ npx pakem-cli install --yes # non-interactive, global default
92
+ npx pakem-cli install --project # ./.claude/skills/pakem
93
+ npx pakem-cli install --dir ~/.agents/skills/pakem
93
94
  ```
94
95
 
95
- The package only copies the skill; it adds no npm dependency to your project. Any other argument is delegated to the bundled Python CLI (`npx pakem init --type app`).
96
+ The package only copies the skill; it adds no npm dependency to your project. Any other argument is delegated to the bundled Python CLI (`npx pakem-cli init --type app`).
96
97
 
97
98
  Requires **Python 3.10+**. The base CLI/Core uses only the standard library. Ed25519 identity operations are optional and require `python -m pip install cryptography`.
98
99
 
package/SKILL.md CHANGED
@@ -4,7 +4,7 @@ description: "Pakem: agent work discipline with finish gates."
4
4
  license: MIT
5
5
  compatibility: Python 3.10+; Linux/macOS tested, Windows best-effort
6
6
  metadata:
7
- version: "1.2.1"
7
+ version: "1.3.0"
8
8
  ---
9
9
 
10
10
  # Pakem
package/npm/bin/pakem.js CHANGED
@@ -2,9 +2,13 @@
2
2
  "use strict";
3
3
 
4
4
  /**
5
- * `npx pakem` installs the Pakem skill; every other argument is delegated to
6
- * the Python CLI that ships inside this package. Pakem stays Python; npm is
5
+ * `npx pakem-cli` installs the Pakem skill; every other argument is delegated
6
+ * to the Python CLI that ships inside this package. Pakem stays Python; npm is
7
7
  * only the delivery mechanism.
8
+ *
9
+ * With a terminal it shows an interactive picker (like other skill installers).
10
+ * Without a TTY, or with explicit flags, it installs non-interactively so agents
11
+ * and CI can call it safely.
8
12
  */
9
13
  const fs = require("fs");
10
14
  const os = require("os");
@@ -17,25 +21,28 @@ const PY = process.env.PAKEM_PYTHON || (process.platform === "win32" ? "python"
17
21
  const SKIP = new Set(["npm", "tests", "node_modules", ".git", ".github", "dist",
18
22
  "__pycache__", ".venv", "venv"]);
19
23
  const SKIP_FILES = new Set([".gitignore", "requirements-dev.txt", "package.json", "package-lock.json"]);
24
+ const HOME = os.homedir();
25
+ const INTERACTIVE = Boolean(process.stdin.isTTY && process.stdout.isTTY);
20
26
 
21
27
  function help() {
22
28
  console.log(`Pakem ${PKG.version}
23
29
 
24
30
  Usage:
25
- npx pakem install the skill into ~/.claude/skills/pakem
26
- npx pakem install [options] same, with options
27
- npx pakem <command> [args...] run the Pakem CLI (init, check, finish, ...)
31
+ npx pakem-cli install the skill (interactive in a terminal)
32
+ npx pakem-cli install [options] same, with options
33
+ npx pakem-cli <command> [args...] run the Pakem CLI (init, check, finish, ...)
28
34
 
29
35
  Install options:
30
36
  --dir <path> install into a specific directory
31
37
  --project install into ./.claude/skills/pakem
32
38
  --force replace an existing installation
33
39
  --dry-run show what would be copied
40
+ -y, --yes never prompt (defaults to ~/.claude/skills/pakem)
34
41
 
35
42
  Examples:
36
- npx pakem
37
- npx pakem install --dir ~/.agents/skills/pakem
38
- npx pakem init --type app`);
43
+ npx pakem-cli
44
+ npx pakem-cli install --dir ~/.agents/skills/pakem
45
+ npx pakem-cli init --type app`);
39
46
  }
40
47
 
41
48
  function fail(message) {
@@ -44,7 +51,14 @@ function fail(message) {
44
51
  }
45
52
 
46
53
  function parseInstallArgs(args) {
47
- const out = { dir: null, project: false, force: false, dryRun: false };
54
+ const out = {
55
+ dir: null,
56
+ project: false,
57
+ force: false,
58
+ dryRun: false,
59
+ yes: false,
60
+ interactive: false,
61
+ };
48
62
  for (let i = 0; i < args.length; i++) {
49
63
  const arg = args[i];
50
64
  if (arg === "--dir") {
@@ -56,6 +70,10 @@ function parseInstallArgs(args) {
56
70
  out.force = true;
57
71
  } else if (arg === "--dry-run") {
58
72
  out.dryRun = true;
73
+ } else if (arg === "-y" || arg === "--yes") {
74
+ out.yes = true;
75
+ } else if (arg === "--interactive") {
76
+ out.interactive = true;
59
77
  } else if (arg === "--help" || arg === "-h") {
60
78
  help();
61
79
  process.exit(0);
@@ -66,11 +84,15 @@ function parseInstallArgs(args) {
66
84
  return out;
67
85
  }
68
86
 
87
+ function expand(target) {
88
+ return path.resolve(String(target).replace(/^~(?=$|\/|\\)/, HOME));
89
+ }
90
+
69
91
  function targetDir(opts) {
70
- if (opts.dir) return path.resolve(opts.dir.replace(/^~(?=$|\/|\\)/, os.homedir()));
92
+ if (opts.dir) return expand(opts.dir);
71
93
  if (opts.project) return path.resolve(process.cwd(), ".claude", "skills", "pakem");
72
- if (process.env.PAKEM_SKILL_DIR) return path.resolve(process.env.PAKEM_SKILL_DIR);
73
- return path.join(os.homedir(), ".claude", "skills", "pakem");
94
+ if (process.env.PAKEM_SKILL_DIR) return expand(process.env.PAKEM_SKILL_DIR);
95
+ return path.join(HOME, ".claude", "skills", "pakem");
74
96
  }
75
97
 
76
98
  function pythonVersion() {
@@ -80,17 +102,16 @@ function pythonVersion() {
80
102
  return probe.stdout.trim();
81
103
  }
82
104
 
83
- function install(opts) {
84
- const dest = targetDir(opts);
85
- if (opts.dryRun) {
86
- console.log(`Would install Pakem ${PKG.version} into ${dest}`);
87
- for (const name of fs.readdirSync(ROOT).sort()) {
88
- if (SKIP.has(name) || SKIP_FILES.has(name)) continue;
89
- console.log(` ${name}`);
90
- }
91
- return;
105
+ function pythonWarning(py) {
106
+ if (!py) return `${PY} not found; Pakem needs Python 3.10+.`;
107
+ const [major, minor] = py.split(".").map(Number);
108
+ if (major < 3 || (major === 3 && minor < 10)) {
109
+ return `Python ${py} found; Pakem needs 3.10+.`;
92
110
  }
111
+ return null;
112
+ }
93
113
 
114
+ function copySkill(dest, opts) {
94
115
  if (fs.existsSync(dest)) {
95
116
  const entries = fs.readdirSync(dest);
96
117
  if (entries.length && !opts.force) {
@@ -103,29 +124,116 @@ function install(opts) {
103
124
  let copied = 0;
104
125
  for (const name of fs.readdirSync(ROOT).sort()) {
105
126
  if (SKIP.has(name) || SKIP_FILES.has(name)) continue;
106
- const src = path.join(ROOT, name);
107
- const dst = path.join(dest, name);
108
- fs.cpSync(src, dst, {
127
+ fs.cpSync(path.join(ROOT, name), path.join(dest, name), {
109
128
  recursive: true,
110
- filter: (from) => !path.basename(from).startsWith(".") || path.basename(from) === ".gitignore",
129
+ filter: (from) => !path.basename(from).startsWith("."),
111
130
  });
112
131
  copied++;
113
132
  }
133
+ return copied;
134
+ }
135
+
136
+ function nextSteps(dest) {
137
+ return [
138
+ `restart your agent so it loads SKILL.md`,
139
+ `cd your-project && ${PY} ${path.join(dest, "scripts", "pakem.py")} init --type app`,
140
+ ];
141
+ }
142
+
143
+ function install(opts) {
144
+ const dest = targetDir(opts);
145
+ if (opts.dryRun) {
146
+ console.log(`Would install Pakem ${PKG.version} into ${dest}`);
147
+ for (const name of fs.readdirSync(ROOT).sort()) {
148
+ if (SKIP.has(name) || SKIP_FILES.has(name)) continue;
149
+ console.log(` ${name}`);
150
+ }
151
+ return;
152
+ }
114
153
 
154
+ const copied = copySkill(dest, opts);
115
155
  const py = pythonVersion();
116
156
  console.log(`Pakem ${PKG.version} installed in ${dest}`);
117
157
  console.log(` ${copied} top-level entries copied`);
118
- if (!py) {
119
- console.log(` [WARN] ${PY} not found. Pakem needs Python 3.10+.`);
120
- } else if (Number(py.split(".")[0]) < 3 || (Number(py.split(".")[0]) === 3 && Number(py.split(".")[1]) < 10)) {
121
- console.log(` [WARN] Python ${py} found; Pakem needs 3.10+.`);
122
- } else {
123
- console.log(` python: ${PY} ${py}`);
158
+ const warning = pythonWarning(py);
159
+ console.log(warning ? ` [WARN] ${warning}` : ` python: ${PY} ${py}`);
160
+ console.log("");
161
+ console.log("Next:");
162
+ for (const line of nextSteps(dest)) console.log(` ${line}`);
163
+ }
164
+
165
+ async function interactiveInstall(seed) {
166
+ const clack = await import("@clack/prompts");
167
+ const { intro, outro, select, text, confirm, spinner, cancel, isCancel } = clack;
168
+
169
+ intro(`Pakem ${PKG.version} · agent work discipline`);
170
+
171
+ const choices = [
172
+ { value: "claude-global", label: "Claude Code (global)", hint: "~/.claude/skills/pakem" },
173
+ { value: "agents-global", label: "Agents / skills.sh (global)", hint: "~/.agents/skills/pakem" },
174
+ { value: "claude-project", label: "This project", hint: "./.claude/skills/pakem" },
175
+ { value: "custom", label: "Custom path", hint: "any skills folder" },
176
+ ];
177
+
178
+ const choice = await select({
179
+ message: "Where should the skill live?",
180
+ options: choices,
181
+ initialValue: seed.dir ? "custom" : seed.project ? "claude-project" : "claude-global",
182
+ });
183
+ if (isCancel(choice)) {
184
+ cancel("Installation cancelled.");
185
+ return;
186
+ }
187
+
188
+ let dest;
189
+ if (choice === "claude-global") dest = path.join(HOME, ".claude", "skills", "pakem");
190
+ else if (choice === "agents-global") dest = path.join(HOME, ".agents", "skills", "pakem");
191
+ else if (choice === "claude-project") dest = path.resolve(process.cwd(), ".claude", "skills", "pakem");
192
+ else {
193
+ const typed = await text({
194
+ message: "Install path",
195
+ placeholder: "~/.agents/skills/pakem",
196
+ initialValue: seed.dir || "",
197
+ validate: (value) => (!value ? "A path is required" : undefined),
198
+ });
199
+ if (isCancel(typed)) {
200
+ cancel("Installation cancelled.");
201
+ return;
202
+ }
203
+ dest = expand(typed);
124
204
  }
205
+
206
+ if (fs.existsSync(dest) && fs.readdirSync(dest).length) {
207
+ if (!seed.force) {
208
+ const replace = await confirm({
209
+ message: `${dest} already exists. Replace it?`,
210
+ initialValue: false,
211
+ });
212
+ if (isCancel(replace) || !replace) {
213
+ cancel("Installation cancelled.");
214
+ return;
215
+ }
216
+ seed.force = true;
217
+ }
218
+ }
219
+
220
+ const spin = spinner();
221
+ spin.start(`Installing into ${dest}`);
222
+ try {
223
+ const copied = copySkill(dest, seed);
224
+ spin.stop(`Installed ${copied} top-level entries`);
225
+ } catch (error) {
226
+ spin.stop("Installation failed");
227
+ throw error;
228
+ }
229
+
230
+ const py = pythonVersion();
231
+ const warning = pythonWarning(py);
232
+ if (warning) outro(`Installed, but ${warning}`);
233
+ else outro(`Installed · python ${py}`);
125
234
  console.log("");
126
235
  console.log("Next:");
127
- console.log(" restart your agent so it loads SKILL.md");
128
- console.log(` cd your-project && ${PY} ${path.join(dest, "scripts", "pakem.py")} init --type app`);
236
+ for (const line of nextSteps(dest)) console.log(` ${line}`);
129
237
  }
130
238
 
131
239
  function runCli(args) {
@@ -136,15 +244,29 @@ function runCli(args) {
136
244
  process.exit(result.status === null ? 1 : result.status);
137
245
  }
138
246
 
139
- const args = process.argv.slice(2);
140
- if (args.length === 0) {
141
- install(parseInstallArgs([]));
142
- } else if (args[0] === "install") {
143
- install(parseInstallArgs(args.slice(1)));
144
- } else if (["--dir", "--project", "--force", "--dry-run"].includes(args[0])) {
145
- install(parseInstallArgs(args));
146
- } else if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
147
- help();
148
- } else {
149
- runCli(args);
247
+ async function main() {
248
+ const args = process.argv.slice(2);
249
+ if (args.length === 0) {
250
+ const opts = parseInstallArgs([]);
251
+ if (INTERACTIVE) return interactiveInstall(opts);
252
+ return install(opts);
253
+ }
254
+ if (args[0] === "install") {
255
+ const opts = parseInstallArgs(args.slice(1));
256
+ const explicit = Boolean(opts.dir || opts.project || opts.yes || opts.dryRun);
257
+ if (opts.interactive || (INTERACTIVE && !explicit)) return interactiveInstall(opts);
258
+ return install(opts);
259
+ }
260
+ if (["--dir", "--project", "--force", "--dry-run", "-y", "--yes"].includes(args[0])) {
261
+ return install(parseInstallArgs(args));
262
+ }
263
+ if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
264
+ help();
265
+ return;
266
+ }
267
+ return runCli(args);
150
268
  }
269
+
270
+ main().catch((error) => {
271
+ fail(error && error.message ? error.message : String(error));
272
+ });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pakem-cli",
3
- "version": "1.2.1",
3
+ "version": "1.3.0",
4
4
  "description": "Agent work discipline with verifiable finish gates: sessions, plans, specs, and gates that can fail.",
5
5
  "bin": {
6
6
  "pakem": "npm/bin/pakem.js"
@@ -53,5 +53,8 @@
53
53
  "homepage": "https://github.com/Matsumiko/pakem",
54
54
  "bugs": {
55
55
  "url": "https://github.com/Matsumiko/pakem/issues"
56
+ },
57
+ "dependencies": {
58
+ "@clack/prompts": "^1.9.0"
56
59
  }
57
60
  }
package/scripts/pakem.py CHANGED
@@ -21,7 +21,7 @@ import uuid
21
21
  from datetime import datetime
22
22
  from pathlib import Path
23
23
 
24
- VERSION = "1.2.1"
24
+ VERSION = "1.3.0"
25
25
  PROTOCOL_VERSION = "1.0"
26
26
  PROTOCOL_EVENTS = {
27
27
  "session.started", "session.abandoned", "session.step_recorded",
@@ -16,7 +16,7 @@ from typing import Any
16
16
 
17
17
  MCP_VERSION = "2026-07-28"
18
18
  SERVER_NAME = "pakem"
19
- SERVER_VERSION = "1.2.1"
19
+ SERVER_VERSION = "1.3.0"
20
20
  META_VERSION = "io.modelcontextprotocol/protocolVersion"
21
21
  META_CLIENT_CAPS = "io.modelcontextprotocol/clientCapabilities"
22
22
  META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo"