@indigoai-us/hq-cloud 6.14.22 → 6.14.24

package/src/local-path-codec.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Regression tests for US-002 (hq-sync-windows-skill-symlink-collision):
+ * the canonical-spelling fixpoint and the mixed-version amplifier round trip.
+ *
+ * Amplifier background: pre-codec engines mint vault keys verbatim from
+ * Windows local names (`core%3Askill`), and post-codec engines escape `%`
+ * before every other character locally — so each pull+re-walk hop across a
+ * mixed-version fleet minted one more percent generation (`%253A`,
+ * `%25253A`, …). These tests pin the two properties that kill the loop:
+ * the walk-back maps a materialized junk key to its EXACT original spelling,
+ * and every generation collapses to one canonical fixpoint for guard lookups.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  canonicalVaultKeySpelling,
+  canonicalVaultSegmentSpelling,
+  localPathForVaultKey,
+  vaultKeyForLocalPath,
+} from "./local-path-codec.js";
+
+describe("canonicalVaultKeySpelling (US-002)", () => {
+  it("collapses every junk percent generation to the same fixpoint", () => {
+    const canonical = ".claude/skills/core:skill/scripts";
+    expect(canonicalVaultKeySpelling(canonical)).toBe(canonical);
+    expect(canonicalVaultKeySpelling(".claude/skills/core%3Askill/scripts")).toBe(canonical);
+    expect(canonicalVaultKeySpelling(".claude/skills/core%253Askill/scripts")).toBe(canonical);
+    expect(canonicalVaultKeySpelling(".claude/skills/core%25253Askill/scripts")).toBe(canonical);
+  });
+
+  it("distinct logical paths keep distinct fixpoints", () => {
+    expect(canonicalVaultKeySpelling("a%3Ab/x")).not.toBe(
+      canonicalVaultKeySpelling("a%3Ac/x"),
+    );
+  });
+
+  it("colon-free percent names are their OWN canonical form — never collapsed (round-9)", () => {
+    // `.claude/skills/foo bar` and `.claude/skills/foo%20bar` are two
+    // distinct legitimate skills; only namespaced (<ns>:<skill>) wrapper
+    // generations participate in the amplifier.
+    expect(canonicalVaultKeySpelling(".claude/skills/foo%20bar/SKILL.md")).toBe(
+      ".claude/skills/foo%20bar/SKILL.md",
+    );
+    expect(canonicalVaultKeySpelling(".claude/skills/foo bar/SKILL.md")).toBe(
+      ".claude/skills/foo bar/SKILL.md",
+    );
+    expect(canonicalVaultSegmentSpelling("foo%20bar")).toBe("foo%20bar");
+    // Namespaced generations still collapse.
+    expect(canonicalVaultSegmentSpelling("ns%3Askill")).toBe("ns:skill");
+  });
+
+  it("stops decoding at the first literal colon — a legitimately percent-named skill stays distinct", () => {
+    // reindex forms `core:foo%3Abar` verbatim from a source dir named
+    // `foo%3Abar`; decoding past the colon would collapse it into the
+    // unrelated `core:foo:bar` family.
+    expect(canonicalVaultKeySpelling(".claude/skills/core:foo%3Abar/SKILL.md")).toBe(
+      ".claude/skills/core:foo%3Abar/SKILL.md",
+    );
+    // The win32-encoded generation of that same weird-but-legit wrapper
+    // decodes exactly one step — back to the colon form, not beyond.
+    expect(
+      canonicalVaultKeySpelling(".claude/skills/core%3Afoo%253Abar/SKILL.md"),
+    ).toBe(".claude/skills/core:foo%3Abar/SKILL.md");
+  });
+
+  it("decodes ONLY the wrapper segment — child-file percent escapes stay verbatim", () => {
+    // `scripts/foo%20bar.sh` and `scripts/foo bar.sh` are distinct objects;
+    // collapsing them would let the doctor/pull guard drop the wrong one.
+    expect(
+      canonicalVaultKeySpelling(".claude/skills/core%3Askill/scripts/foo%20bar.sh"),
+    ).toBe(".claude/skills/core:skill/scripts/foo%20bar.sh");
+    expect(
+      canonicalVaultKeySpelling(".claude/skills/core:skill/scripts/foo%20bar.sh"),
+    ).toBe(".claude/skills/core:skill/scripts/foo%20bar.sh");
+  });
+
+  it("returns non-skills keys verbatim — the amplifier only exists in the wrapper namespace", () => {
+    expect(canonicalVaultKeySpelling("notes/a%3Ab.md")).toBe("notes/a%3Ab.md");
+    expect(canonicalVaultKeySpelling("notes/a%20b.md")).toBe("notes/a%20b.md");
+  });
+
+  it("leaves a % that is not a two-hex-digit escape alone", () => {
+    // Matches decodeLocalVaultSegment: only `%XX` (hex) is an escape.
+    expect(canonicalVaultKeySpelling("notes/50%-done.md")).toBe("notes/50%-done.md");
+  });
+});
+
+describe("mixed-version amplifier round trip (US-002)", () => {
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "codec-amp-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it("a literal %3A key pulled + re-walked with win32=true maps back to the EXACT original key — no %253A generation", () => {
+    // Key minted by a pre-codec engine from a Windows local farm name.
+    const win32 = true;
+    const junkKey = ".claude/skills/core%3Askill/scripts";
+
+    // Pull leg: materialize at the codec-derived local path. `%` is escaped
+    // before every other character, so the on-disk dir name is
+    // `core%253Askill` — that escape is exactly what makes the walk-back
+    // unambiguous instead of colliding with the canonical `core:skill` key.
+    const localPath = localPathForVaultKey(tmpRoot, junkKey, win32);
+    fs.mkdirSync(localPath, { recursive: true });
+    const farmEntries = fs.readdirSync(
+      path.join(tmpRoot, ".claude", "skills"),
+    );
+    expect(farmEntries).toEqual(["core%253Askill"]);
+
+    // Re-walk leg: the push walker maps the materialized name back to a key
+    // (share.ts walkDir convention: vaultKeyForLocalPath on the abs path).
+    const rewalkedKey = vaultKeyForLocalPath(tmpRoot, localPath, win32);
+
+    // The amplifier is dead only if this is the EXACT original spelling —
+    // any NEW spelling would upload as a fresh junk key generation.
+    expect(rewalkedKey).toBe(junkKey);
+    expect(rewalkedKey).not.toContain("%253A");
+  });
+
+  it("the canonical ':' key and its '%3A' twin materialize at DISTINCT local paths and round-trip independently", () => {
+    const win32 = true;
+    const canonicalLocal = localPathForVaultKey(tmpRoot, "farm/a:b", win32);
+    const junkLocal = localPathForVaultKey(tmpRoot, "farm/a%3Ab", win32);
+    // No on-disk collision between the two key families …
+    expect(canonicalLocal).not.toBe(junkLocal);
+    // … and each walks back to its own exact spelling.
+    expect(vaultKeyForLocalPath(tmpRoot, canonicalLocal, win32)).toBe("farm/a:b");
+    expect(vaultKeyForLocalPath(tmpRoot, junkLocal, win32)).toBe("farm/a%3Ab");
+  });
+});

package/src/local-path-codec.ts

@@ -93,3 +93,69 @@ export function vaultKeyForLocalPath(
     .map((segment) => decodeLocalVaultSegment(segment, win32))
     .join("/");
 }
+
+/**
+ * Collapse a vault-key spelling to its canonical logical form by repeatedly
+ * percent-decoding every segment to a fixpoint.
+ *
+ * Mixed-version amplifier context: a pre-codec Windows engine uploads its
+ * local farm names verbatim, minting keys like `core%3Askill`; a post-codec
+ * engine that materializes that key re-escapes the `%` on its next walk, and
+ * a pre-codec peer re-uploads `core%253Askill` — one junk generation per hop.
+ * Every generation decodes to the same fixpoint (`core:skill`), so the
+ * fixpoint — never the raw spelling — is the identity of the logical path.
+ * Decodes with win32 semantics unconditionally: junk spellings are a
+ * key-space (wire) phenomenon, not a host-platform one. Used by the pull
+ * planner's junk-spelling guard; deliberately NEVER used to rewrite keys
+ * (journals and the wire always keep the exact spelling they were minted
+ * with — collapsing families is the vault doctor's job, US-003).
+ */
+export function canonicalVaultSegmentSpelling(segment: string): string {
+  // Junk generations are encodings of the FULL canonical wrapper name, so a
+  // generation never contains a literal ':' — the colon is what got encoded
+  // (`ns:skill` -> `ns%3Askill` -> `ns%253Askill` -> ...). The decode loop
+  // therefore stops the moment a spelling contains a colon: that IS the
+  // canonical form. This keeps a legitimately-percent-named skill distinct —
+  // reindex forms `core:foo%3Abar` verbatim from a source dir named
+  // `foo%3Abar`, and decoding past the colon would wrongly collapse it into
+  // `core:foo:bar`. (Colon-free names with %XX, e.g. `foo%20bar`, still
+  // decode — that is the cross-platform unification of a win32-encoded
+  // wrapper for canonical `foo bar`; a POSIX source dir literally named
+  // `foo%20bar` is inherently ambiguous, and the doctor's marker-body
+  // safety gate bounds what can be auto-deleted for such names.)
+  let current = segment;
+  while (!current.includes(":")) {
+    const decoded = decodeLocalVaultSegment(current, true);
+    if (decoded === current) break;
+    current = decoded;
+  }
+  // A decode chain that never reaches a colon is NOT an amplifier family —
+  // generated wrapper generations always decode back to `<ns>:<skill>`. A
+  // colon-free percent name (`foo%20bar`) is a legitimate skill's own
+  // spelling, distinct from `foo bar`; collapsing it would let the pull
+  // guard skip it and the doctor rewrite-then-delete real content. Return
+  // the ORIGINAL spelling so colon-free names are always their own
+  // canonical form.
+  return current.includes(":") ? current : segment;
+}
+
+export function canonicalVaultKeySpelling(key: string): string {
+  // Only the WRAPPER directory name under `.claude/skills/` is subject to
+  // the mixed-version spelling amplifier — platforms disagree solely about
+  // how the `<ns>:<skill>` name is spelled on disk. Child segments keep
+  // their percent escapes verbatim (`scripts/foo%20bar.sh` and
+  // `scripts/foo bar.sh` are DISTINCT objects); decoding them too would
+  // collapse legitimate files into one family and let the doctor or pull
+  // guard skip/tombstone the wrong object. Non-skills keys pass through
+  // untouched for the same reason.
+  const segments = key.split("/");
+  if (
+    segments.length < 3 ||
+    segments[0] !== ".claude" ||
+    segments[1] !== "skills"
+  ) {
+    return key;
+  }
+  segments[2] = canonicalVaultSegmentSpelling(segments[2]!);
+  return segments.join("/");
+}

package/src/machine-auth.test.ts

@@ -19,14 +19,17 @@ import { pathToFileURL } from "url";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 let originalHome: string | undefined;
+let originalUserProfile: string | undefined;
 let originalCredsEnv: string | undefined;
 let tmpHome: string;
 
 beforeEach(() => {
   originalHome = process.env.HOME;
+  originalUserProfile = process.env.USERPROFILE;
   originalCredsEnv = process.env.HQ_MACHINE_CREDS_FILE;
   tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "hq-machine-auth-test-"));
   process.env.HOME = tmpHome;
+  process.env.USERPROFILE = tmpHome;
   delete process.env.HQ_MACHINE_CREDS_FILE;
   vi.resetModules();
 });
@@ -35,6 +38,8 @@ afterEach(() => {
   vi.useRealTimers();
   if (originalHome === undefined) delete process.env.HOME;
   else process.env.HOME = originalHome;
+  if (originalUserProfile === undefined) delete process.env.USERPROFILE;
+  else process.env.USERPROFILE = originalUserProfile;
   if (originalCredsEnv === undefined) delete process.env.HQ_MACHINE_CREDS_FILE;
   else process.env.HQ_MACHINE_CREDS_FILE = originalCredsEnv;
   fs.rmSync(tmpHome, { recursive: true, force: true });