taktcli 0.8.0__tar.gz → 0.8.2__tar.gz

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.
Files changed (71) hide show
  1. {taktcli-0.8.0 → taktcli-0.8.2}/PKG-INFO +45 -7
  2. {taktcli-0.8.0 → taktcli-0.8.2}/README.md +44 -6
  3. {taktcli-0.8.0 → taktcli-0.8.2}/pyproject.toml +4 -1
  4. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/__main__.py +2 -1
  5. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/__init__.py +2 -1
  6. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/auth.py +3 -0
  7. taktcli-0.8.2/taktcli/commands/skill.py +236 -0
  8. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/wikis.py +45 -5
  9. taktcli-0.8.2/taktcli/skills/explore-wiki/SKILL.md +13 -0
  10. taktcli-0.8.2/taktcli/skills/takt/SKILL.md +125 -0
  11. taktcli-0.8.2/taktcli/skills/takt/references/cli.md +126 -0
  12. taktcli-0.8.2/taktcli/skills/takt/references/explore-wiki.md +71 -0
  13. taktcli-0.8.2/taktcli/skills/takt/references/grooming.md +79 -0
  14. taktcli-0.8.2/taktcli/skills/takt/references/plumbing.md +131 -0
  15. taktcli-0.8.2/taktcli/skills/takt/references/tasks.md +159 -0
  16. taktcli-0.8.2/taktcli/skills/takt/references/wiki-writing.md +78 -0
  17. taktcli-0.8.2/taktcli/skills/takt/references/wiki.md +113 -0
  18. taktcli-0.8.2/taktcli/skills/takt/references/worker.md +166 -0
  19. taktcli-0.8.2/taktcli/skills/takt-cli/SKILL.md +22 -0
  20. taktcli-0.8.2/taktcli/skills/takt-worker/SKILL.md +23 -0
  21. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli.egg-info/PKG-INFO +45 -7
  22. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli.egg-info/SOURCES.txt +14 -0
  23. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_auth_commands.py +4 -0
  24. taktcli-0.8.2/tests/test_skill.py +263 -0
  25. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_wikis.py +42 -5
  26. {taktcli-0.8.0 → taktcli-0.8.2}/setup.cfg +0 -0
  27. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/__init__.py +0 -0
  28. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/auth.py +0 -0
  29. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/_exec.py +0 -0
  30. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/_run.py +0 -0
  31. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/file.py +0 -0
  32. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/gql.py +0 -0
  33. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/hotpath.py +0 -0
  34. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/label.py +0 -0
  35. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/notif.py +0 -0
  36. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/project.py +0 -0
  37. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/schema.py +0 -0
  38. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/task.py +0 -0
  39. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/watch.py +0 -0
  40. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/wiki.py +0 -0
  41. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/commands/workspace.py +0 -0
  42. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/credentials.py +0 -0
  43. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/errors.py +0 -0
  44. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/introspection.py +0 -0
  45. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/io.py +0 -0
  46. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/oauth.py +0 -0
  47. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/transport.py +0 -0
  48. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli/watch.py +0 -0
  49. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli.egg-info/dependency_links.txt +0 -0
  50. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli.egg-info/entry_points.txt +0 -0
  51. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli.egg-info/requires.txt +0 -0
  52. {taktcli-0.8.0 → taktcli-0.8.2}/taktcli.egg-info/top_level.txt +0 -0
  53. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_auth.py +0 -0
  54. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_cli.py +0 -0
  55. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_credentials.py +0 -0
  56. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_file.py +0 -0
  57. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_gql.py +0 -0
  58. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_hotpath.py +0 -0
  59. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_introspection.py +0 -0
  60. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_io.py +0 -0
  61. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_label.py +0 -0
  62. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_notif.py +0 -0
  63. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_project.py +0 -0
  64. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_refresh_concurrency.py +0 -0
  65. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_schema.py +0 -0
  66. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_task.py +0 -0
  67. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_transport.py +0 -0
  68. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_version.py +0 -0
  69. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_watch.py +0 -0
  70. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_wiki.py +0 -0
  71. {taktcli-0.8.0 → taktcli-0.8.2}/tests/test_workspace.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: taktcli
3
- Version: 0.8.0
3
+ Version: 0.8.2
4
4
  Summary: Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core
5
5
  Author: Takt
6
6
  License: MIT
@@ -40,6 +40,30 @@ pip install -e cli/ # from a monorepo checkout
40
40
  Maestro/harness images ship `pip install 'taktcli[watch]'` — `taktcli watch` is
41
41
  the supported replacement for the retired `tools/wait_for_task.py`.
42
42
 
43
+ ## Agent skill
44
+
45
+ The wheel ships **`/takt`**, an agent skill (`SKILL.md` + `references/`) that
46
+ teaches any skill-loading agent (Claude Code, Codex, opencode, …) to drive Takt
47
+ with this CLI. It always documents the installed version.
48
+
49
+ ```bash
50
+ taktcli skill show # print SKILL.md (no install needed)
51
+ taktcli skill show references/worker.md # any file in the skill
52
+ taktcli skill path # where the bundled copy lives
53
+ taktcli skill install # copy to ~/.claude/skills/takt
54
+ taktcli skill install --target agents # ~/.agents/skills/takt
55
+ taktcli skill install --target codex # $CODEX_HOME/skills/takt (default ~/.codex/skills)
56
+ taktcli skill install --target project # ./.claude/skills/takt
57
+ taktcli skill install --dir DIR # DIR/takt
58
+ taktcli skill install --aliases # also the takt-cli, explore-wiki, takt-worker aliases
59
+ ```
60
+
61
+ Modes: `/takt cli` (CLI reference), `/takt explore-wiki` (wiki exploration),
62
+ `/takt worker` (take a task end to end). `install` copies the files (never a
63
+ symlink) and writes `VERSION`: the version, then one `sha256 path` line per
64
+ file. It refuses to replace a copy that was edited, has no `VERSION`, is a
65
+ symlink, or comes from a newer taktcli, unless `--force`.
66
+
43
67
  ## Quickstart
44
68
 
45
69
  ```bash
@@ -204,7 +228,8 @@ Every MCP tool maps to a verb:
204
228
  | *(none — CLI-only; MCP tool removed in takt-432)* | `wiki feedback resolve <id>` |
205
229
  | `wiki_list` | `wikis list` |
206
230
  | `create_wiki` | `wikis create` |
207
- | *(none — CLI-only; GraphQL `updateWiki`)* | `wikis update <slug>` |
231
+ | *(none — CLI-only; GraphQL `updateWiki` / `renameWiki`)* | `wikis update <slug>` |
232
+ | *(none — CLI-only; GraphQL `wikiRenamePreview`)* | `wikis rename-preview <slug> --new-slug S` |
208
233
  | `get_project_wiki` | `wikis get <project>` |
209
234
  | `request_upload_url_and_headers` + `confirm_upload` | `file upload <path>` (composite) |
210
235
  | `get_file_url` | `file url <id>` |
@@ -242,6 +267,7 @@ taktcli wikis update knowledge --name "Team knowledge"
242
267
  taktcli wikis update knowledge --description "Shared documentation"
243
268
  taktcli wikis update knowledge --description-file description.md
244
269
  taktcli wikis update knowledge --description-file -
270
+ taktcli wikis rename-preview knowledge --new-slug team-docs
245
271
  taktcli wikis update knowledge --new-slug team-docs --yes-rewrite-links
246
272
  ```
247
273
 
@@ -251,13 +277,25 @@ stores an empty string. `--description-file` reads UTF-8 text (`-` reads stdin)
251
277
  and cannot be combined with `--description`. Name and description require
252
278
  `write:wiki` within the token's workspace and wiki allowlist.
253
279
 
254
- `--new-slug` requires `--yes-rewrite-links`; omitting confirmation exits `3`
255
- before sending a request. Confirmation does not bypass the server's human OWNER
256
- check. Actual slug changes currently return `NOT_IMPLEMENTED` with a clear server
257
- message on stderr and exit `1`, pending mention reconciliation in takt-428.
258
280
  Successful metadata updates print `{"updateWiki":{"slug":…, "name":…,
259
281
  "description":…}}`; `--raw` and `--compact` follow the normal output contract.
260
- Rewrite counts and unfixable links are not returned by the current server.
282
+
283
+ `--new-slug` renames the slug through `renameWiki`. It requires
284
+ `--yes-rewrite-links`; omitting confirmation exits `3` before sending a request.
285
+ Confirmation does not bypass the server's check that the caller is a human
286
+ workspace OWNER (`FORBIDDEN` otherwise). The rename rewrites every `[[old/…]]`
287
+ mention and app URL into the wiki (`https://takt.sh/wiki/old/…`,
288
+ `/w/<workspace>/wiki/old/…`, relative `/wiki/old/…`) across the workspace's pages,
289
+ tasks, comments, results and descriptions, in one transaction, and prints
290
+ `{"renameWiki":{"wiki":{…},"report":{"oldSlug","newSlug","pages","tasks",
291
+ "comments","results","links","unfixable"}}}`. `unfixable` lists what Takt cannot
292
+ reach (env such as `WIKI_SLUG`/`TAKT_WIKI`, CLAUDE.md, skills, scripts,
293
+ bookmarks, links on other hosts). The old slug 404s. Combined with `--name` /
294
+ `--description`, both mutations go in one document, rename first; if the rename
295
+ fails, the metadata edit does not run.
296
+
297
+ `rename-preview` runs `wikiRenamePreview` and prints the same report without
298
+ writing anything. It is gated like the rename.
261
299
 
262
300
  ## Output & exit codes
263
301
 
@@ -24,6 +24,30 @@ pip install -e cli/ # from a monorepo checkout
24
24
  Maestro/harness images ship `pip install 'taktcli[watch]'` — `taktcli watch` is
25
25
  the supported replacement for the retired `tools/wait_for_task.py`.
26
26
 
27
+ ## Agent skill
28
+
29
+ The wheel ships **`/takt`**, an agent skill (`SKILL.md` + `references/`) that
30
+ teaches any skill-loading agent (Claude Code, Codex, opencode, …) to drive Takt
31
+ with this CLI. It always documents the installed version.
32
+
33
+ ```bash
34
+ taktcli skill show # print SKILL.md (no install needed)
35
+ taktcli skill show references/worker.md # any file in the skill
36
+ taktcli skill path # where the bundled copy lives
37
+ taktcli skill install # copy to ~/.claude/skills/takt
38
+ taktcli skill install --target agents # ~/.agents/skills/takt
39
+ taktcli skill install --target codex # $CODEX_HOME/skills/takt (default ~/.codex/skills)
40
+ taktcli skill install --target project # ./.claude/skills/takt
41
+ taktcli skill install --dir DIR # DIR/takt
42
+ taktcli skill install --aliases # also the takt-cli, explore-wiki, takt-worker aliases
43
+ ```
44
+
45
+ Modes: `/takt cli` (CLI reference), `/takt explore-wiki` (wiki exploration),
46
+ `/takt worker` (take a task end to end). `install` copies the files (never a
47
+ symlink) and writes `VERSION`: the version, then one `sha256 path` line per
48
+ file. It refuses to replace a copy that was edited, has no `VERSION`, is a
49
+ symlink, or comes from a newer taktcli, unless `--force`.
50
+
27
51
  ## Quickstart
28
52
 
29
53
  ```bash
@@ -188,7 +212,8 @@ Every MCP tool maps to a verb:
188
212
  | *(none — CLI-only; MCP tool removed in takt-432)* | `wiki feedback resolve <id>` |
189
213
  | `wiki_list` | `wikis list` |
190
214
  | `create_wiki` | `wikis create` |
191
- | *(none — CLI-only; GraphQL `updateWiki`)* | `wikis update <slug>` |
215
+ | *(none — CLI-only; GraphQL `updateWiki` / `renameWiki`)* | `wikis update <slug>` |
216
+ | *(none — CLI-only; GraphQL `wikiRenamePreview`)* | `wikis rename-preview <slug> --new-slug S` |
192
217
  | `get_project_wiki` | `wikis get <project>` |
193
218
  | `request_upload_url_and_headers` + `confirm_upload` | `file upload <path>` (composite) |
194
219
  | `get_file_url` | `file url <id>` |
@@ -226,6 +251,7 @@ taktcli wikis update knowledge --name "Team knowledge"
226
251
  taktcli wikis update knowledge --description "Shared documentation"
227
252
  taktcli wikis update knowledge --description-file description.md
228
253
  taktcli wikis update knowledge --description-file -
254
+ taktcli wikis rename-preview knowledge --new-slug team-docs
229
255
  taktcli wikis update knowledge --new-slug team-docs --yes-rewrite-links
230
256
  ```
231
257
 
@@ -235,13 +261,25 @@ stores an empty string. `--description-file` reads UTF-8 text (`-` reads stdin)
235
261
  and cannot be combined with `--description`. Name and description require
236
262
  `write:wiki` within the token's workspace and wiki allowlist.
237
263
 
238
- `--new-slug` requires `--yes-rewrite-links`; omitting confirmation exits `3`
239
- before sending a request. Confirmation does not bypass the server's human OWNER
240
- check. Actual slug changes currently return `NOT_IMPLEMENTED` with a clear server
241
- message on stderr and exit `1`, pending mention reconciliation in takt-428.
242
264
  Successful metadata updates print `{"updateWiki":{"slug":…, "name":…,
243
265
  "description":…}}`; `--raw` and `--compact` follow the normal output contract.
244
- Rewrite counts and unfixable links are not returned by the current server.
266
+
267
+ `--new-slug` renames the slug through `renameWiki`. It requires
268
+ `--yes-rewrite-links`; omitting confirmation exits `3` before sending a request.
269
+ Confirmation does not bypass the server's check that the caller is a human
270
+ workspace OWNER (`FORBIDDEN` otherwise). The rename rewrites every `[[old/…]]`
271
+ mention and app URL into the wiki (`https://takt.sh/wiki/old/…`,
272
+ `/w/<workspace>/wiki/old/…`, relative `/wiki/old/…`) across the workspace's pages,
273
+ tasks, comments, results and descriptions, in one transaction, and prints
274
+ `{"renameWiki":{"wiki":{…},"report":{"oldSlug","newSlug","pages","tasks",
275
+ "comments","results","links","unfixable"}}}`. `unfixable` lists what Takt cannot
276
+ reach (env such as `WIKI_SLUG`/`TAKT_WIKI`, CLAUDE.md, skills, scripts,
277
+ bookmarks, links on other hosts). The old slug 404s. Combined with `--name` /
278
+ `--description`, both mutations go in one document, rename first; if the rename
279
+ fails, the metadata edit does not run.
280
+
281
+ `rename-preview` runs `wikiRenamePreview` and prints the same report without
282
+ writing anything. It is gated like the rename.
245
283
 
246
284
  ## Output & exit codes
247
285
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "taktcli"
3
- version = "0.8.0"
3
+ version = "0.8.2"
4
4
  description = "Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -26,6 +26,9 @@ testpaths = ["tests"]
26
26
  [tool.setuptools.packages.find]
27
27
  include = ["taktcli*"]
28
28
 
29
+ [tool.setuptools.package-data]
30
+ taktcli = ["skills/**/*"]
31
+
29
32
  [build-system]
30
33
  requires = ["setuptools>=75"]
31
34
  build-backend = "setuptools.build_meta"
@@ -9,6 +9,7 @@ import argparse
9
9
  import sys
10
10
 
11
11
  from . import __version__, auth, commands
12
+ from .commands.skill import ADVERT
12
13
  from .errors import TaktCliError
13
14
 
14
15
  DOCS_HINT = (
@@ -31,7 +32,7 @@ def build_parser() -> TaktArgumentParser:
31
32
  parser = TaktArgumentParser(
32
33
  prog="taktcli",
33
34
  description="Authorized GraphQL CLI for Takt — full GraphQL surface from the shell.",
34
- epilog=DOCS_HINT,
35
+ epilog=f"{DOCS_HINT} {ADVERT}.",
35
36
  )
36
37
  parser.add_argument("--version", action="version", version=f"taktcli {__version__}")
37
38
  parser.add_argument(
@@ -9,7 +9,7 @@ today because all current groups are wired through their own modules.
9
9
 
10
10
  from ..errors import ConfigError
11
11
  from ..io import add_shared_io_args
12
- from . import auth, file, gql, hotpath, label, notif, project, schema, task, watch, wiki, wikis, workspace
12
+ from . import auth, file, gql, hotpath, label, notif, project, schema, skill, task, watch, wiki, wikis, workspace
13
13
 
14
14
  NOUN_GROUPS = {}
15
15
 
@@ -67,5 +67,6 @@ def register(subparsers) -> None:
67
67
  notif.register(subparsers)
68
68
  project.register(subparsers)
69
69
  watch.register(subparsers)
70
+ skill.register(subparsers)
70
71
  for name, spec in NOUN_GROUPS.items():
71
72
  _add_group(subparsers, name, spec, "")
@@ -26,6 +26,7 @@ from ..auth import DEFAULT_URL, profile_name, reauthorize, resolve_credential
26
26
  from ..credentials import CredentialStore, expires_at_from, parse_expiry
27
27
  from ..errors import ConfigError, TransportError
28
28
  from ..transport import execute
29
+ from .skill import ADVERT
29
30
 
30
31
  REQUEST_DEVICE_CODE = """
31
32
  mutation RequestDeviceCode($clientName: String) {
@@ -300,6 +301,7 @@ def run_login(args, *, opener=None, sleep=None, out=None, stdout=None, open_brow
300
301
  current = store.read().get("current_profile")
301
302
  print(summary_line(profile, name), file=stdout)
302
303
  stdout.flush()
304
+ print(ADVERT, file=out)
303
305
  if current != name:
304
306
  print(
305
307
  f"Profile {name!r} saved; the current profile is still {current!r}. "
@@ -390,6 +392,7 @@ def run_whoami(args, *, opener=None, out=None) -> int:
390
392
  print(f"expires: {_describe_expiry(profile.get('expires_at'))} · {refresh}", file=out)
391
393
  print(f"source: {cred.source}", file=out)
392
394
  print(f"endpoint: {cred.url}", file=out)
395
+ print(ADVERT, file=out)
393
396
  out.flush()
394
397
  return 0
395
398
 
@@ -0,0 +1,236 @@
1
+ """``taktcli skill <verb>`` — the bundled ``/takt`` agent skill.
2
+
3
+ The wheel ships the skill as package data under ``taktcli/skills/``: the ``takt``
4
+ skill itself plus thin alias skills (``takt-cli``, ``explore-wiki``,
5
+ ``takt-worker``) that point at it. Because it ships with the CLI, the skill
6
+ always documents the installed CLI version.
7
+
8
+ - ``show [FILE]`` prints ``SKILL.md`` (or one of its references) to stdout, so an
9
+ agent can read the skill without installing it.
10
+ - ``path`` prints the bundled skill directory.
11
+ - ``install`` copies (never symlinks) the skill into a skills directory and
12
+ writes a ``VERSION`` file: the version on line 1, then ``sha256sum``-style
13
+ lines for every installed file. Those hashes are how a later install tells a
14
+ pristine copy (safe to replace) from an edited one (refused without
15
+ ``--force``). A copy from a newer taktcli is refused the same way.
16
+ """
17
+
18
+ import hashlib
19
+ import json
20
+ import os
21
+ import re
22
+ import shutil
23
+ import sys
24
+ import tempfile
25
+ from dataclasses import dataclass
26
+ from pathlib import Path
27
+
28
+ from .. import __version__
29
+ from ..errors import ConfigError
30
+
31
+ SKILL_NAME = "takt"
32
+ VERSION_FILE = "VERSION"
33
+ BUNDLE_DIR = Path(__file__).resolve().parent.parent / "skills"
34
+ INSTALLED = "installed"
35
+ UPDATED = "updated"
36
+ UNCHANGED = "unchanged"
37
+ ADVERT = "Agent skill: taktcli skill install (or taktcli skill show)"
38
+
39
+
40
+ def _target_roots() -> dict:
41
+ """Map each ``--target`` to its skills root directory."""
42
+ home = Path.home()
43
+ codex_home = os.environ.get("CODEX_HOME")
44
+ return {
45
+ "claude": home / ".claude" / "skills",
46
+ "agents": home / ".agents" / "skills",
47
+ "codex": (Path(codex_home) if codex_home else home / ".codex") / "skills",
48
+ "project": Path.cwd() / ".claude" / "skills",
49
+ }
50
+
51
+
52
+ def register(subparsers) -> None:
53
+ """Register the ``skill`` noun group and its verbs."""
54
+ help_text = "the bundled /takt agent skill: show, path, install"
55
+ group = subparsers.add_parser("skill", help=help_text, description=help_text)
56
+ verbs = group.add_subparsers(dest="skill_verb", metavar="<verb>", required=True)
57
+
58
+ show = verbs.add_parser(
59
+ "show",
60
+ help="print SKILL.md (or one of its files) to stdout",
61
+ description="print the bundled /takt SKILL.md, or FILE relative to the skill directory",
62
+ )
63
+ show.add_argument("file", nargs="?", default="SKILL.md", metavar="FILE", help="e.g. references/worker.md")
64
+ show.set_defaults(func=run_show)
65
+
66
+ path = verbs.add_parser("path", help="print the bundled skill directory", description="print the bundled skill directory")
67
+ path.set_defaults(func=run_path)
68
+
69
+ install = verbs.add_parser(
70
+ "install",
71
+ help="copy the skill into a skills directory",
72
+ description=(
73
+ "copy the /takt skill to <root>/takt and write <root>/takt/VERSION. "
74
+ "Refuses to replace an edited copy or one from a newer taktcli unless --force."
75
+ ),
76
+ )
77
+ where = install.add_mutually_exclusive_group()
78
+ where.add_argument(
79
+ "--target",
80
+ choices=sorted(_target_roots()),
81
+ default="claude",
82
+ help="claude: ~/.claude/skills · agents: ~/.agents/skills · codex: $CODEX_HOME/skills (default ~/.codex/skills) "
83
+ "· project: ./.claude/skills (default: claude)",
84
+ )
85
+ where.add_argument("--dir", metavar="DIR", help="skills root to install into (the skill lands in DIR/takt)")
86
+ install.add_argument("--aliases", action="store_true", help="also install the takt-cli, explore-wiki and takt-worker aliases")
87
+ install.add_argument("--force", action="store_true", help="overwrite an edited copy or one from a newer taktcli")
88
+ install.set_defaults(func=run_install)
89
+
90
+
91
+ def bundled_skills() -> list[str]:
92
+ """Names of the bundled skills: ``takt`` first, then its aliases."""
93
+ names = sorted(p.name for p in BUNDLE_DIR.iterdir() if (p / "SKILL.md").is_file())
94
+ return [SKILL_NAME] + [n for n in names if n != SKILL_NAME]
95
+
96
+
97
+ def skill_files(root: Path) -> dict[str, Path]:
98
+ """Every file under ``root`` (except ``VERSION``), keyed by POSIX relative path."""
99
+ files = {}
100
+ for path in sorted(root.rglob("*")):
101
+ if path.is_file() and "__pycache__" not in path.parts:
102
+ rel = path.relative_to(root).as_posix()
103
+ if rel != VERSION_FILE:
104
+ files[rel] = path
105
+ return files
106
+
107
+
108
+ def digest(path: Path) -> str:
109
+ """SHA-256 hex digest of a file's bytes."""
110
+ return hashlib.sha256(path.read_bytes()).hexdigest()
111
+
112
+
113
+ def render_version(version: str, hashes: dict[str, str]) -> str:
114
+ """The ``VERSION`` file: version line, then ``<sha256> <path>`` lines."""
115
+ lines = [version] + [f"{sha} {rel}" for rel, sha in sorted(hashes.items())]
116
+ return "\n".join(lines) + "\n"
117
+
118
+
119
+ def parse_version_file(text: str) -> tuple[str, dict[str, str]]:
120
+ """Parse a ``VERSION`` file into ``(version, {path: sha256})``."""
121
+ lines = text.splitlines()
122
+ version = lines[0].strip() if lines else ""
123
+ hashes = {}
124
+ for line in lines[1:]:
125
+ sha, sep, rel = line.partition(" ")
126
+ if sep:
127
+ hashes[rel.strip()] = sha.strip()
128
+ return version, hashes
129
+
130
+
131
+ def version_key(version: str) -> tuple[int, ...]:
132
+ """A comparable key from the numeric release part of a version string."""
133
+ release = re.match(r"\d+(?:\.\d+)*", version or "")
134
+ return tuple(int(part) for part in release.group(0).split(".")) if release else ()
135
+
136
+
137
+ def edited_files(dest: Path, recorded: dict[str, str]) -> list[str]:
138
+ """Files in ``dest`` that differ from, or are missing from, its recorded hashes."""
139
+ present = skill_files(dest)
140
+ changed = [rel for rel, path in present.items() if recorded.get(rel) != digest(path)]
141
+ missing = [rel for rel in recorded if rel not in present]
142
+ return sorted(changed + missing)
143
+
144
+
145
+ @dataclass(frozen=True)
146
+ class InstallPlan:
147
+ """What ``install`` will do to one skill: ``action`` and, if it needs ``--force``, why."""
148
+
149
+ name: str
150
+ dest: Path
151
+ hashes: dict
152
+ action: str
153
+ problem: str | None = None
154
+
155
+
156
+ def plan_install(name: str, root: Path) -> InstallPlan:
157
+ """Decide, without writing anything, how bundled skill ``name`` lands in ``root/name``."""
158
+ dest = root / name
159
+ hashes = {rel: digest(path) for rel, path in skill_files(BUNDLE_DIR / name).items()}
160
+ if not (dest.is_symlink() or dest.exists()):
161
+ return InstallPlan(name, dest, hashes, INSTALLED)
162
+ if dest.is_symlink() or not dest.is_dir():
163
+ return InstallPlan(name, dest, hashes, UPDATED, f"{dest} is a symlink or not a directory")
164
+ version_path = dest / VERSION_FILE
165
+ if not version_path.is_file():
166
+ return InstallPlan(name, dest, hashes, UPDATED, "it has no VERSION file, so it was not installed by taktcli")
167
+ version, recorded = parse_version_file(version_path.read_text(encoding="utf-8"))
168
+ edited = edited_files(dest, recorded)
169
+ if edited:
170
+ return InstallPlan(name, dest, hashes, UPDATED, f"it was edited since install ({', '.join(edited)})")
171
+ if version_key(version) > version_key(__version__):
172
+ return InstallPlan(
173
+ name, dest, hashes, UPDATED, f"it is from taktcli {version}, newer than this taktcli {__version__}"
174
+ )
175
+ if version == __version__ and recorded == hashes:
176
+ return InstallPlan(name, dest, hashes, UNCHANGED)
177
+ return InstallPlan(name, dest, hashes, UPDATED)
178
+
179
+
180
+ def apply_install(plan: InstallPlan) -> dict:
181
+ """Carry out a plan: stage a fresh copy plus ``VERSION`` next to the target, then swap it in."""
182
+ result = {"skill": plan.name, "path": str(plan.dest), "version": __version__, "action": plan.action}
183
+ if plan.action == UNCHANGED:
184
+ return result
185
+ dest = plan.dest
186
+ dest.parent.mkdir(parents=True, exist_ok=True)
187
+ staging = Path(tempfile.mkdtemp(prefix=f".{plan.name}-", dir=dest.parent))
188
+ try:
189
+ shutil.copytree(BUNDLE_DIR / plan.name, staging, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__"))
190
+ (staging / VERSION_FILE).write_text(render_version(__version__, plan.hashes), encoding="utf-8")
191
+ if dest.is_symlink() or dest.is_file():
192
+ dest.unlink()
193
+ elif dest.exists():
194
+ shutil.rmtree(dest)
195
+ os.replace(staging, dest)
196
+ finally:
197
+ if staging.exists():
198
+ shutil.rmtree(staging)
199
+ return result
200
+
201
+
202
+ def run_install(args, *, out=None) -> int:
203
+ """``taktcli skill install`` — plan every skill first, refuse before writing, then install."""
204
+ out = out if out is not None else sys.stdout
205
+ root = Path(args.dir).expanduser() if args.dir else _target_roots()[args.target]
206
+ names = bundled_skills() if args.aliases else [SKILL_NAME]
207
+ plans = [plan_install(name, root) for name in names]
208
+ refused = [plan for plan in plans if plan.problem and not args.force]
209
+ if refused:
210
+ reasons = "; ".join(f"{plan.dest}: {plan.problem}" for plan in refused)
211
+ raise ConfigError(f"Refusing to overwrite (nothing was written): {reasons}. Pass --force to replace.")
212
+ results = [apply_install(plan) for plan in plans]
213
+ print(json.dumps({"installed": results}, indent=2), file=out)
214
+ out.flush()
215
+ return 0
216
+
217
+
218
+ def run_show(args, *, out=None) -> int:
219
+ """``taktcli skill show [FILE]`` — print a file of the bundled skill."""
220
+ out = out if out is not None else sys.stdout
221
+ base = (BUNDLE_DIR / SKILL_NAME).resolve()
222
+ path = (base / args.file).resolve()
223
+ if not path.is_relative_to(base) or not path.is_file():
224
+ available = ", ".join(skill_files(base))
225
+ raise ConfigError(f"No file {args.file!r} in the bundled skill. Available: {available}")
226
+ out.write(path.read_text(encoding="utf-8"))
227
+ out.flush()
228
+ return 0
229
+
230
+
231
+ def run_path(args, *, out=None) -> int:
232
+ """``taktcli skill path`` — print the bundled skill directory."""
233
+ out = out if out is not None else sys.stdout
234
+ print(BUNDLE_DIR / SKILL_NAME, file=out)
235
+ out.flush()
236
+ return 0
@@ -40,14 +40,25 @@ def register(subparsers) -> None:
40
40
  p.add_argument("--name", help="new Wiki name")
41
41
  p.add_argument("--description", "--desc", help="new description (empty string clears the text)")
42
42
  p.add_argument("--description-file", help="read description from a UTF-8 file; - for stdin")
43
- p.add_argument("--new-slug", help="request a new slug (currently unavailable on the server)")
43
+ p.add_argument(
44
+ "--new-slug",
45
+ help="rename the slug (workspace OWNER); rewrites every [[slug/…]] link and app URL to the wiki",
46
+ )
44
47
  p.add_argument(
45
48
  "--yes-rewrite-links", action="store_true",
46
- help="confirm a slug request that will rewrite links across the workspace when supported",
49
+ help="confirm a slug rename that rewrites links across the workspace",
47
50
  )
48
51
  add_output_args(p)
49
52
  p.set_defaults(func=update)
50
53
 
54
+ p = verbs.add_parser(
55
+ "rename-preview", help="show what a slug rename would rewrite, without changing anything",
56
+ )
57
+ p.add_argument("slug", help="current Wiki slug (explicit; does not use TAKT_WIKI)")
58
+ p.add_argument("--new-slug", required=True, help="the slug to preview renaming to")
59
+ add_output_args(p)
60
+ p.set_defaults(func=rename_preview)
61
+
51
62
  p = verbs.add_parser("get", help="get a project's Wiki")
52
63
  p.add_argument("project")
53
64
  add_output_args(p)
@@ -69,7 +80,17 @@ def create(args) -> int:
69
80
  return run_op(args, document, {"input": wiki_input})
70
81
 
71
82
 
83
+ REPORT_FIELDS = "oldSlug newSlug pages tasks comments results links unfixable"
84
+
85
+
72
86
  def update(args) -> int:
87
+ """Edit name/description via ``updateWiki``; a ``--new-slug`` goes through ``renameWiki``.
88
+
89
+ A rename prints ``renameWiki.report`` (per-surface counts, ``links``, ``unfixable``). With a
90
+ name or description too, both fields travel in one mutation document, ``renameWiki`` first:
91
+ mutation fields run serially and a failed rename stops the document, so the metadata edit
92
+ lands on the new slug or not at all.
93
+ """
73
94
  if args.new_slug is not None and not args.yes_rewrite_links:
74
95
  raise ConfigError("--new-slug requires --yes-rewrite-links to confirm workspace-wide link rewriting")
75
96
  description = resolve_text(args.description, args.description_file, "description")
@@ -78,10 +99,21 @@ def update(args) -> int:
78
99
  wiki_input["name"] = args.name
79
100
  if description is not None:
80
101
  wiki_input["description"] = description
81
- if args.new_slug is not None:
82
- wiki_input["slug"] = args.new_slug
83
- if not wiki_input:
102
+ if not wiki_input and args.new_slug is None:
84
103
  raise ConfigError("provide at least one of --name, --description, --description-file, --new-slug")
104
+ if args.new_slug is not None:
105
+ rename = (
106
+ "renameWiki(slug:$slug,newSlug:$newSlug){"
107
+ f"wiki{{slug name description}} report{{{REPORT_FIELDS}}}}}"
108
+ )
109
+ variables = {"slug": args.slug, "newSlug": args.new_slug}
110
+ if not wiki_input:
111
+ return run_op(args, f"mutation($slug:String!,$newSlug:String!){{{rename}}}", variables)
112
+ document = (
113
+ "mutation($slug:String!,$newSlug:String!,$input:UpdateWikiInput!){"
114
+ f"{rename} updateWiki(slug:$newSlug,input:$input){{slug name description}}}}"
115
+ )
116
+ return run_op(args, document, {**variables, "input": wiki_input})
85
117
  document = (
86
118
  "mutation($slug:String!,$input:UpdateWikiInput!){"
87
119
  "updateWiki(slug:$slug,input:$input){slug name description}}"
@@ -89,6 +121,14 @@ def update(args) -> int:
89
121
  return run_op(args, document, {"slug": args.slug, "input": wiki_input})
90
122
 
91
123
 
124
+ def rename_preview(args) -> int:
125
+ document = (
126
+ "query($slug:String!,$newSlug:String!){"
127
+ f"wikiRenamePreview(slug:$slug,newSlug:$newSlug){{{REPORT_FIELDS}}}}}"
128
+ )
129
+ return run_op(args, document, {"slug": args.slug, "newSlug": args.new_slug})
130
+
131
+
92
132
  def get(args) -> int:
93
133
  document = (
94
134
  "query($slug:String!){"
@@ -0,0 +1,13 @@
1
+ ---
2
+ name: explore-wiki
3
+ description: Alias of `/takt explore-wiki`. Load Takt wiki context before work by searching and reading pages via taktcli, in parallel by angle, then synthesizing. Use proactively when starting a task that may have documented architecture, conventions or prior decisions; when asked to "explore the wiki", "check the wiki", "what does the wiki say about"; or before grepping *.md files for project knowledge. Skip if the project has no wiki.
4
+ ---
5
+
6
+ # /explore-wiki = /takt explore-wiki
7
+
8
+ This skill is an alias. The content lives in the `takt` skill next to this one:
9
+
10
+ 1. Read `../takt/SKILL.md` (setup, rules, the common recipes).
11
+ 2. Then `../takt/references/explore-wiki.md` (the exploration recipe).
12
+
13
+ No `../takt/` directory? Run `taktcli skill show` and `taktcli skill show references/explore-wiki.md`, or install it with `taktcli skill install`.