@alessandroraffa/tangyr 6.0.1 → 7.0.0

package/README.md

@@ -60,6 +60,7 @@ Options declared on individual commands in addition to the [global flags](#globa
 | Command                                                  | Option                   | Description                                                                                                                                                                                                                  |
 | -------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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`. |
+| `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             |
 | `install`, `sync`                                        | `--ignore-errors`        | Suppress exit code `3` when the loss report contains `error`-severity entries                                                                                                                                                |
 | `install`, `sync`                                        | `--kit <name>`           | Kit to install/synchronize: `<name>` for a local source, `<name>@<version>` for a remote one                                                                                                                                 |
 | `install`, `uninstall`, `assess`                         | `--tools <list>`         | Comma-separated list of target tools                                                                                                                                                                                         |
@@ -509,3 +510,16 @@ Precedence: `--claude-config-dir` flag > `TANGYR_CLAUDE_CONFIG_DIRS` env > `clau
 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.
 
 The manifest records the full set of roots written so that `verify` and `uninstall` operate on all of them.
+
+## Documentation
+
+| Document                                                                           | For                                                                                                                                                              |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [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 |
+| [Authoring a project-local kit](docs/guides/authoring-a-project-local-kit.md)      | Writing a kit and installing it into a repository                                                                                                                |
+| [Installing a private kit](docs/guides/kit-consumer-onboarding.md)                 | Consuming a kit from a signed remote origin                                                                                                                      |
+| [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                                                            |
+| [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                                                |
+| [Mapping declarations](mappings/README.md)                                         | The declarative translation inputs under `mappings/`                                                                                                             |
+
+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.

package/dist/index.js

@@ -15930,7 +15930,8 @@ function readManifest(scopePath) {
     // and `uninstall` is a different process from `install`. The shared-surface
     // records went out to disk correctly and arrived as `undefined`, which put
     // removal back on the marker-based guess this exists to replace.
-    sharedSurfaces: Array.isArray(parsed.sharedSurfaces) ? parsed.sharedSurfaces : void 0
+    sharedSurfaces: Array.isArray(parsed.sharedSurfaces) ? parsed.sharedSurfaces : void 0,
+    kit: typeof parsed.kit === "object" && parsed.kit !== null && typeof parsed.kit.name === "string" ? parsed.kit : void 0
   };
 }
 function readStrictManifest(scopePath) {
@@ -16710,6 +16711,21 @@ function makeResolver(scope, projectRoot, tool) {
     return resolved;
   };
 }
+function slotsForScope(scopeMap, scope, projectRoot) {
+  if (scope !== "project") {
+    return scopeMap?.global;
+  }
+  const projectSlots = scopeMap?.project;
+  if (!projectSlots) {
+    return void 0;
+  }
+  const root = projectRoot ?? process.cwd();
+  const resolved = {};
+  for (const [slot, value] of Object.entries(projectSlots)) {
+    resolved[slot] = typeof value === "string" ? path9.resolve(root, value) : value;
+  }
+  return resolved;
+}
 
 // src/mappings/loader.ts
 var import_yaml4 = __toESM(require_dist(), 1);
@@ -25383,7 +25399,7 @@ function checkClaudeCode(options, findings, config, sourceRoot, configDir, logge
     checkParentWritablePath(artifact.path, artifact.component, findings);
   }
 }
-function slotsForScope(config, sourceRoot, configDir, target, options) {
+function slotsForScope2(config, sourceRoot, configDir, target, options) {
   const scopeMap = loadMappings(sourceRoot, config, configDir).platformPaths.targets[target];
   const scope = options.scope ?? config.scope ?? "global";
   if (scope !== "project") {
@@ -25405,7 +25421,7 @@ function slotsForScope(config, sourceRoot, configDir, target, options) {
   return resolved;
 }
 function checkCopilot(config, sourceRoot, configDir, findings, options) {
-  const globalPaths = slotsForScope(
+  const globalPaths = slotsForScope2(
     config,
     sourceRoot,
     configDir,
@@ -25428,7 +25444,7 @@ function checkCopilot(config, sourceRoot, configDir, findings, options) {
   }
 }
 function checkCodex(config, sourceRoot, configDir, findings, logger, options) {
-  const globalPaths = slotsForScope(
+  const globalPaths = slotsForScope2(
     config,
     sourceRoot,
     configDir,
@@ -32032,9 +32048,35 @@ async function runInstallCommand(options, logger) {
     logger.warn(
       `Existing Tangyr installation found in ${scopePath} (archetype: ${existingManifest.archetype}, version: ${existingManifest.version})`
     );
+    const installedKit = existingManifest.kit;
+    const switchingKit = installedKit !== void 0 && installedKit.name !== kitInfo.name;
     let action;
-    if (options.yes) {
+    if (switchingKit && options.replace) {
+      logger.warn(
+        `Replacing '${installedKit.name}' (${installedKit.version}) with '${kitInfo.name}' (${kitInfo.version}): the installed kit is uninstalled first, which restores what it displaced.`
+      );
+      action = "clean-install";
+    } else if (switchingKit && options.yes) {
+      logger.error(
+        `This scope holds the kit '${installedKit.name}' (${installedKit.version}), not '${kitInfo.name}'.`
+      );
+      logger.error(
+        `Installing over it would leave both kits' artifacts in place, and every target would read both. Pass --replace to uninstall '${installedKit.name}' first and install '${kitInfo.name}' in its place, or run \`tangyr uninstall\` yourself. If you meant to update '${installedKit.name}', check kitPath in your configuration.`
+      );
+      process.exit(1);
+    } else if (options.yes) {
       action = "update";
+    } else if (switchingKit) {
+      action = await dist_default8({
+        message: `This scope holds '${installedKit.name}'. Installing '${kitInfo.name}' over it would leave both. Choose an action:`,
+        choices: [
+          {
+            name: `Replace (uninstall '${installedKit.name}', then install '${kitInfo.name}')`,
+            value: "clean-install"
+          },
+          { name: "Abort", value: "abort" }
+        ]
+      });
     } else if (!process.stdin.isTTY) {
       logger.error(
         "Existing installation requires an explicit action. Pass --yes to update, or run interactively."
@@ -32293,6 +32335,7 @@ SKIPPED CONFLICTS (${skippedTargetPaths.size} target(s) left unchanged):`
   ensureScope(scopePath);
   const manifest = existingManifest ?? createEmptyManifest(kitInfo.archetype, kitInfo.kitFormat, scope);
   manifest.tools = [.../* @__PURE__ */ new Set([...manifest.tools, ...tools])];
+  manifest.kit = { name: kitInfo.name, version: kitInfo.version };
   manifest.files = [];
   for (const backup of backupsToAdd) {
     manifest.backups.push(backup);
@@ -34221,25 +34264,10 @@ function classifyDirectoryPresence(component, dirPath) {
     conformant: present
   };
 }
-function slotsForScope2(scopeMap, scope, projectRoot) {
-  if (scope !== "project") {
-    return scopeMap?.global;
-  }
-  const projectSlots = scopeMap?.project;
-  if (!projectSlots) {
-    return void 0;
-  }
-  const root = projectRoot ?? process.cwd();
-  const resolved = {};
-  for (const [slot, value] of Object.entries(projectSlots)) {
-    resolved[slot] = typeof value === "string" ? path51.resolve(root, value) : value;
-  }
-  return resolved;
-}
 function classifyCodexFiles(config, sourceRoot, configDir, scope, projectRoot) {
   const mappings = loadMappings(sourceRoot, config, configDir);
   const scopeMap = mappings.platformPaths.targets.codex;
-  const paths = slotsForScope2(scopeMap, scope, projectRoot);
+  const paths = slotsForScope(scopeMap, scope, projectRoot);
   if (!paths?.instructions || !paths.agents || !paths.skills || !paths.hooks_shared_file || !paths.mcp_shared_file || !paths.rules) {
     throw new Error("platform-paths.yaml: incomplete codex path mapping");
   }
@@ -34387,7 +34415,7 @@ function classifyCodexHooksFile(filePath) {
 function classifyCopilotFiles(config, sourceRoot, configDir, scope, projectRoot) {
   const mappings = loadMappings(sourceRoot, config, configDir);
   const scopeMap = mappings.platformPaths.targets.copilot;
-  const paths = slotsForScope2(scopeMap, scope, projectRoot);
+  const paths = slotsForScope(scopeMap, scope, projectRoot);
   if (!paths?.agents || !paths.skills || !paths.prompts || !paths.hooks || !paths.mcp_shared_file) {
     throw new Error("platform-paths.yaml: incomplete copilot path mapping");
   }
@@ -35327,6 +35355,16 @@ async function runSyncCommand(options, logger) {
   const lossReport = createLossReport();
   const mappings = targets.includes("copilot") || targets.includes("codex") || targets.includes("opencode") || targets.includes("cursor") || targets.includes("cline") || targets.some((target) => isDeferredTarget(target)) ? loadMappings(sourceRoot, config, configDir) : void 0;
   const kitSync = kitInfo ? prepareKitManifest(syncOptions.scope, syncOptions.projectRoot, kitInfo) : void 0;
+  const installedKit = kitSync?.manifest.kit;
+  if (kitInfo && installedKit && installedKit.name !== kitInfo.name) {
+    logger.error(
+      `This scope holds the kit '${installedKit.name}' (${installedKit.version}), and the configuration names '${kitInfo.name}'.`
+    );
+    logger.error(
+      `sync updates the installed kit; it does not replace it. Run \`tangyr install --replace\` to put '${kitInfo.name}' in its place, or check kitPath if you meant to update '${installedKit.name}'.`
+    );
+    process.exit(1);
+  }
   if (kitInfo && kitSync && options.dryRun) {
     printManifestDiff(logger, kitInfo.name, kitSync.diff);
   }
@@ -35609,6 +35647,7 @@ function updateManifest(kitInfo, kitSync) {
       });
     }
   }
+  kitSync.manifest.kit = { name: kitInfo.name, version: kitInfo.version };
   refreshArtifactStates(kitSync.manifest.artifacts);
   writeManifest(kitSync.scopePath, kitSync.manifest);
 }
@@ -35691,11 +35730,16 @@ function cleanupRemovedManagedArtifacts(config, mappings, targets, options, remo
     return;
   }
   const currentComponent = options.component;
-  const copilotPaths = mappings.platformPaths.targets.copilot.global;
-  const codexPaths = mappings.platformPaths.targets.codex.global;
-  const opencodePaths = mappings.platformPaths.targets.opencode.global;
-  const cursorPaths = mappings.platformPaths.targets.cursor.global;
-  const clinePaths = mappings.platformPaths.targets.cline.global;
+  const scopeOf = (target) => slotsForScope(
+    mappings.platformPaths.targets[target],
+    options.scope,
+    options.projectRoot
+  );
+  const copilotPaths = scopeOf("copilot");
+  const codexPaths = scopeOf("codex");
+  const opencodePaths = scopeOf("opencode");
+  const cursorPaths = scopeOf("cursor");
+  const clinePaths = scopeOf("cline");
   for (const relativePath of removedSourcePaths) {
     const component = componentForRemovedSource(relativePath, config);
     if (currentComponent && component !== currentComponent) {
@@ -36829,7 +36873,10 @@ function buildProgram() {
   ).option(
     "--json",
     `Emit {"degraded": true} on stderr only when this resolution fell back to a warm cache after a network failure; otherwise this flag has no effect and output is unchanged \u2014 unlike --json on other commands, which always replaces the command's entire output.`
-  ).option("--tools <list>", "Comma-separated list of target tools").option("--loss-report <path>", "Write semantic loss report JSON to a file").option("--scope <scope>", "Installation scope: global or project").option(
+  ).option("--tools <list>", "Comma-separated list of target tools").option("--loss-report <path>", "Write semantic loss report JSON to a file").option(
+    "--replace",
+    "Install this kit over a different one already in this scope, uninstalling that one first"
+  ).option("--scope <scope>", "Installation scope: global or project").option(
     "--ignore-errors",
     "Suppress exit code 3 when error-severity loss entries are present"
   ).action(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alessandroraffa/tangyr",
-  "version": "6.0.1",
+  "version": "7.0.0",
   "description": "CLI for the Tangyr discipline — install and manage operating kits for AI coding tools",
   "license": "MIT",
   "engines": {