Skip to content

Commit 96a1844

Browse files
fix(skills): render -o table and -o csv as the skills tables, and name DEEPCTL_SKILLS_REF in a bad-ref error
Review round 10 on PR #111: - status and list print their own tables for -o table, and one row per tool for -o csv, instead of a key/value dump with Python reprs - an invalid DEEPCTL_SKILLS_REF raises SkillRefInvalidError naming the variable and how to clear it; login and plugin stop advising a retry - under -o json/yaml, status and list return the same error document for a skills.json that is not JSON as for one with the wrong shape - the skills errors keep their __dict__ through pickle and copy - docstrings describe that nothing is written for tools with no skills directory Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent b22ded7 commit 96a1844

11 files changed

Lines changed: 652 additions & 109 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -325,16 +325,22 @@ is treated as unset.
325325
`dg skills status` and `dg skills list` both show the installed ref.
326326

327327
Those two commands return a document under `-o json` or `-o yaml`, with the
328-
human table only in the default mode, so they are safe to pipe:
328+
human table only in the default mode, so they are safe to pipe. `-o table`
329+
prints the same table as the default mode, and `-o csv` prints one row per
330+
tool under that table's column names:
329331

330332
```bash
331333
dg -o json skills status | jq '.tools[].skills_ref'
332334
dg -o json skills list | jq '.installed[].count'
335+
dg -o csv skills list
333336
```
334337

335338
A failed download, an unknown ref, or an upstream manifest that does not match
336339
the directories it lists is a hard failure (exit 1) with nothing written. A
337340
partial install is indistinguishable from a complete one once it is on disk.
341+
When the bad ref came from `DEEPCTL_SKILLS_REF`, whether it is missing upstream
342+
or not shaped like a ref, the error names the variable and says to set it to
343+
another ref or unset it.
338344

339345
**deepctl only ever touches skill folder paths it installed.** Those
340346
directories are shared: your own skills and other publishers' skills live in
@@ -369,15 +375,19 @@ them too. So `dg skills` records every folder it writes in
369375
`skills.json`. Both go through the same ownership rules, but any skills
370376
problem there, a collision, a download failure, a `skills.json` deepctl
371377
cannot read, or a crash in the step itself, prints a warning on stderr that
372-
names it and says which `dg skills` command retries it. The warning never changes
378+
names it and says which `dg skills` command retries it. For a bad
379+
`DEEPCTL_SKILLS_REF` it says to change the variable first, since a retry
380+
would fail the same way. The warning never changes
373381
whether the login or the plugin operation succeeded, or its exit code. Run
374382
`dg skills install` to see the error and get the exit code.
375383
- If you delete `skills.json`, deepctl can no longer prove it installed
376384
anything: `remove` deletes nothing and `install` reports the collision rather
377385
than reclaiming the folders. Delete them by hand, then install again. A
378386
`skills.json` deepctl cannot parse is an error, not a reset: every `dg skills`
379387
subcommand exits 1 naming the file, so a hand edit that went wrong cannot
380-
quietly turn Deepgram's folders into somebody else's.
388+
quietly turn Deepgram's folders into somebody else's. Under `-o json` or
389+
`-o yaml`, `status` and `list` still print their document, with `status`
390+
set to `error` and a message naming the file.
381391
- The list holds *paths*, not fingerprints. Delete a folder deepctl installed
382392
and put your own folder, or a file, at the same path without running
383393
`dg skills remove --cli <tool>`, and deepctl still counts it as its own: the

‎packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -279,6 +279,7 @@ def _maybe_prompt_skills_setup(self) -> None:
279279
# without deepctl recording that it owns it.
280280
from deepctl_core.skill_bundle import (
281281
SkillFetchError,
282+
SkillRefInvalidError,
282283
SkillRefNotFoundError,
283284
)
284285
from deepctl_core.skill_generator import (
@@ -329,16 +330,18 @@ def load_state() -> dict[str, Any]:
329330
except SkillFetchError as exc:
330331
# Nothing was written, so there is no ownership to save.
331332
# Say so rather than leaving the banner above unanswered.
332-
# Worded for both causes: a download that failed and a
333-
# DEEPCTL_SKILLS_REF that was refused before any download.
334333
# A ref missing upstream (DEEPCTL_SKILLS_REF or the pinned
335-
# tag) fails the same way on every retry, so that one gets
336-
# the way to choose another ref instead.
334+
# tag), or a DEEPCTL_SKILLS_REF refused for its shape before
335+
# any download, fails the same way on every retry, so those
336+
# get the way to choose another ref instead. Anything else
337+
# is a download that failed, and a retry can work.
337338
_skills_warning(
338339
with_advice(
339340
f"Could not install the Deepgram skills: {exc}",
340341
exc.advice("dg skills install")
341-
if isinstance(exc, SkillRefNotFoundError)
342+
if isinstance(
343+
exc, (SkillRefNotFoundError, SkillRefInvalidError)
344+
)
342345
else "Run 'dg skills install' to retry.",
343346
)
344347
)

‎packages/deepctl-cmd-login/tests/unit/test_login_command.py‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -998,13 +998,14 @@ def ask(*_args, **_kwargs):
998998
assert "Skipped the Deepgram skills install" in said
999999
assert "'installed_skills'" in said
10001000

1001-
def test_an_invalid_environment_ref_is_reported_with_one_full_stop(
1001+
def test_an_invalid_environment_ref_names_the_variable_not_a_retry(
10021002
self, tmp_path, monkeypatch, capsys
10031003
):
1004-
"""The reason ends in a period already; the warning used to add one.
1004+
"""A retry reads the same DEEPCTL_SKILLS_REF and fails the same way.
10051005
1006-
It also said "Could not download" for a ref refused before any
1007-
download began.
1006+
The warning said "Run 'dg skills install' to retry." without naming
1007+
the variable. It also said "Could not download" for a ref refused
1008+
before any download began, and doubled the reason's full stop.
10081009
"""
10091010
from deepctl_core.skill_bundle import REF_ENV_VAR
10101011

@@ -1015,8 +1016,13 @@ def test_an_invalid_environment_ref_is_reported_with_one_full_stop(
10151016
said = " ".join(capsys.readouterr().err.split())
10161017
assert "Could not install the Deepgram skills: Invalid skills ref" in said
10171018
assert "Could not download" not in said
1018-
assert "segment. Run 'dg skills install' to retry." in said
1019-
assert ".. Run" not in said
1019+
assert (
1020+
f"segment. That ref came from {REF_ENV_VAR}. Set it to another ref, "
1021+
"or unset it to use the pinned release. Then run 'dg skills install'."
1022+
in said
1023+
)
1024+
assert "to retry" not in said
1025+
assert ".. " not in said.replace("'..'", "")
10201026
gen.install_skills.assert_not_called()
10211027

10221028
@pytest.mark.parametrize(

‎packages/deepctl-cmd-plugin/src/deepctl_cmd_plugin/command.py‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1265,6 +1265,7 @@ def not_a_map() -> Exception:
12651265
try:
12661266
from deepctl_core.skill_bundle import (
12671267
SkillFetchError,
1268+
SkillRefInvalidError,
12681269
SkillRefNotFoundError,
12691270
)
12701271
from deepctl_core.skill_generator import (
@@ -1363,13 +1364,16 @@ def fetch() -> list[Any]:
13631364
except SkillFetchError as exc:
13641365
# Nothing was written, so the records still describe
13651366
# what is on disk. Say the refresh did not happen. A ref
1366-
# missing upstream fails the same way on every retry, so
1367-
# that one gets the way to choose another ref instead.
1367+
# missing upstream, or one refused for its shape, fails the
1368+
# same way on every retry, so those get the way to choose
1369+
# another ref instead.
13681370
_skills_warning(
13691371
with_advice(
13701372
f"AI assistant skills not updated: {exc}",
13711373
exc.advice("dg skills update")
1372-
if isinstance(exc, SkillRefNotFoundError)
1374+
if isinstance(
1375+
exc, (SkillRefNotFoundError, SkillRefInvalidError)
1376+
)
13731377
else "Run 'dg skills update' to retry.",
13741378
)
13751379
)

‎packages/deepctl-cmd-plugin/tests/unit/test_plugin_command.py‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1289,9 +1289,11 @@ def test_the_updated_line_goes_to_stderr(self, tmp_path, capsys):
12891289
assert captured.out == ""
12901290
assert "AI assistant skills updated" in captured.err
12911291

1292-
def test_an_invalid_environment_ref_is_reported_with_one_full_stop(
1292+
def test_an_invalid_environment_ref_names_the_variable_not_a_retry(
12931293
self, tmp_path, monkeypatch, capsys
12941294
):
1295+
"""`dg skills update` reads the same DEEPCTL_SKILLS_REF, so "retry"
1296+
failed the same way."""
12951297
from deepctl_core.skill_bundle import REF_ENV_VAR
12961298

12971299
monkeypatch.setenv(REF_ENV_VAR, "a..b")
@@ -1301,8 +1303,13 @@ def test_an_invalid_environment_ref_is_reported_with_one_full_stop(
13011303

13021304
said = " ".join(capsys.readouterr().err.split())
13031305
assert "AI assistant skills not updated: Invalid skills ref" in said
1304-
assert "segment. Run 'dg skills update' to retry." in said
1305-
assert ".. Run" not in said
1306+
assert (
1307+
f"segment. That ref came from {REF_ENV_VAR}. Set it to another ref, "
1308+
"or unset it to use the pinned release. Then run 'dg skills update'."
1309+
in said
1310+
)
1311+
assert "to retry" not in said
1312+
assert ".. " not in said.replace("'..'", "")
13061313
gen.install_skills.assert_not_called()
13071314

13081315
def test_a_recorded_ref_gone_upstream_advises_choosing_another(

0 commit comments

Comments
 (0)