@alessandroraffa/tangyr 6.0.0 → 7.0.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/README.md +37 -17
- package/dist/index.js +740 -624
- package/mappings/loss-severity.yaml +5 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -57,22 +57,23 @@ tangyr <command>
|
|
|
57
57
|
|
|
58
58
|
Options declared on individual commands in addition to the [global flags](#global-flags) below. `--offline`, `--refresh`, and `install`/`sync`'s narrow `--json` are documented in [Remote kit source](#remote-kit-source); `--scope` in [Scope](#scope).
|
|
59
59
|
|
|
60
|
-
| Command | Option | Description
|
|
61
|
-
| -------------------------------------------------------- | ------------------------ |
|
|
62
|
-
| `install`, `sync` | `--loss-report <path>` | Write this run's semantic loss report to `<path
|
|
63
|
-
| `install
|
|
64
|
-
| `install`, `sync` | `--
|
|
65
|
-
| `install`, `
|
|
66
|
-
| `
|
|
67
|
-
| `sync
|
|
68
|
-
| `sync` | `--
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
60
|
+
| Command | Option | Description |
|
|
61
|
+
| -------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| `install`, `sync` | `--loss-report <path>` | Write an **extra copy** of this run's semantic loss report to `<path>`. The report itself is scope state and is rewritten at `<scope>/loss.json` by every `install` and `sync` regardless, whether or not the run exits `3`. |
|
|
63
|
+
| `install` | `--replace` | Install this kit over a different one already in this scope: the installed kit is uninstalled first, which restores what it displaced. Without it, a change of kit is refused rather than performed as an update |
|
|
64
|
+
| `install`, `sync` | `--ignore-errors` | Suppress exit code `3` when the loss report contains `error`-severity entries |
|
|
65
|
+
| `install`, `sync` | `--kit <name>` | Kit to install/synchronize: `<name>` for a local source, `<name>@<version>` for a remote one |
|
|
66
|
+
| `install`, `uninstall`, `assess` | `--tools <list>` | Comma-separated list of target tools |
|
|
67
|
+
| `sync`, `status`, `verify`, `doctor`, `cleanup`, `probe` | `--target <tool>` | Limit the command to a single target |
|
|
68
|
+
| `sync` | `--component <name>` | Limit sync to one component type: `instructions`, `agents`, `skills`, `commands`, `rules`, `hooks`, `mcp`, `settings`, `output-styles`, `lsp` |
|
|
69
|
+
| `sync` | `--force` | Rewrite managed artifacts even when provenance matches |
|
|
70
|
+
| `doctor` | `--fix` | Apply safe automated fixes |
|
|
71
|
+
| `cleanup` | `--all` | Include all enabled targets |
|
|
72
|
+
| `config` | `--edit` | Interactively edit mutable config fields |
|
|
73
|
+
| `auth login` | `--skip-validation` | Store the credential without contacting the configured origin |
|
|
74
|
+
| `kit update` | `--kit <name>@<version>` | Remote kit reference to re-fetch into the cache |
|
|
75
|
+
| `cache clear` | `[target]` | Positional: kit name or `<name>@<version>`; omit to clear the whole cache |
|
|
76
|
+
| `assess`, `detect`, `list`, `probe`, `validate` | `--json` | Replace the command's output with JSON |
|
|
76
77
|
|
|
77
78
|
### Authentication
|
|
78
79
|
|
|
@@ -385,7 +386,13 @@ What reached each target (measured on disk):
|
|
|
385
386
|
|
|
386
387
|
Measured on the files, not on what the compilers intended: the two have disagreed, and the files are what the target reads. Nothing is printed when everything arrived; `--verbose` shows the block either way.
|
|
387
388
|
|
|
388
|
-
The same fact reaches `--loss-report <path>` as a `rule-not-delivered`, `agent-not-delivered`, `command-not-delivered`, `skill-not-delivered` or `hook-not-delivered` entry, one per artifact per target, at `error` severity — so a run that loses part of the kit exits `3` rather than reporting success. A category the target has no surface for at all is left to the structural entry that already says so (`persona-not-representable`, `hook-as-plugin`), rather than repeated once per artifact.
|
|
389
|
+
The same fact reaches the loss report — `<scope>/loss.json`, rewritten by every `install` and `sync`, plus any `--loss-report <path>` copy — as a `rule-not-delivered`, `agent-not-delivered`, `command-not-delivered`, `skill-not-delivered` or `hook-not-delivered` entry, one per artifact per target, at `error` severity — so a run that loses part of the kit exits `3` rather than reporting success. A category the target has no surface for at all is left to the structural entry that already says so (`persona-not-representable`, `hook-as-plugin`), rather than repeated once per artifact.
|
|
390
|
+
|
|
391
|
+
## The loss report
|
|
392
|
+
|
|
393
|
+
`.tangyr/loss.json` (project scope) or `~/.tangyr/loss.json` (global) is written by every `install` and `sync`, and removed by `uninstall` with the manifest. It holds one entry per target and component that could not be translated natively, each with its closed-vocabulary type, its severity and a human-readable detail, under a `generatedAt` timestamp.
|
|
394
|
+
|
|
395
|
+
It used to be written only when `--loss-report <path>` was passed, which nobody passes twice: a project found theirs five days stale, naming a component renamed since, while the kit had grown from two components to thirty-four. A report that is only ever a photograph of one run does not belong in a directory that looks like state.
|
|
389
396
|
|
|
390
397
|
## Exit codes
|
|
391
398
|
|
|
@@ -503,3 +510,16 @@ Precedence: `--claude-config-dir` flag > `TANGYR_CLAUDE_CONFIG_DIRS` env > `clau
|
|
|
503
510
|
Per-root artifacts (instructions, agents, skills, commands, rules, output-styles, hooks settings) are written under each root. Shared artifacts (`~/.claude.json` for MCP, `~/.agents/hooks` for hooks) are resolved from the platform default and written once regardless of how many roots are configured.
|
|
504
511
|
|
|
505
512
|
The manifest records the full set of roots written so that `verify` and `uninstall` operate on all of them.
|
|
513
|
+
|
|
514
|
+
## Documentation
|
|
515
|
+
|
|
516
|
+
| Document | For |
|
|
517
|
+
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
518
|
+
| [Operating Tangyr in a project](docs/guides/operating-tangyr-in-a-project.md) | Running the CLI in a repository you did not set up: what it copies, rewrites and deletes, how to read a run, and how to tell a defect from a target that changed |
|
|
519
|
+
| [Authoring a project-local kit](docs/guides/authoring-a-project-local-kit.md) | Writing a kit and installing it into a repository |
|
|
520
|
+
| [Installing a private kit](docs/guides/kit-consumer-onboarding.md) | Consuming a kit from a signed remote origin |
|
|
521
|
+
| [Functional specification](docs/specifications/tangyr-cli-functional-spec-v1.0.md) | What the tool must do: the canonical taxonomy, the per-target contracts, the loss and conflict models |
|
|
522
|
+
| [Maintaining this CLI](docs/maintaining-the-cli.md) | Working on the tool itself: the decisions the code cannot explain, and the traps that have already cost something |
|
|
523
|
+
| [Mapping declarations](mappings/README.md) | The declarative translation inputs under `mappings/` |
|
|
524
|
+
|
|
525
|
+
The dated records under `docs/stepledgers/`, `docs/plans/`, `docs/reports/`, `docs/initiatives/` and `docs/archive/` describe work as it was done and are not maintained against the current behaviour.
|