@indigoai-us/hq-cloud 6.15.0 → 6.15.2

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

@@ -1,138 +0,0 @@
-/**
- * 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

@@ -1,161 +0,0 @@
-/**
- * Reversible local filename adapter for canonical vault keys on Win32.
- *
- * Vault keys are POSIX identifiers and may contain ':' (for example
- * `factory:slack`).  Win32 cannot materialize those strings as filename
- * segments, so keep the key canonical in S3 and journals while encoding only
- * the local segment that reaches the filesystem.
- */
-import * as path from "path";
-
-const WIN32_RESERVED_CHARS = /[<>:"/\\|?*]/;
-const WIN32_DEVICE_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
-
-function isWin32ReservedCharacter(char: string): boolean {
-  return char.charCodeAt(0) <= 0x1f || WIN32_RESERVED_CHARS.test(char);
-}
-
-function percentEscape(char: string): string {
-  return `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
-}
-
-/**
- * Encode one canonical vault-key segment for a Win32 filename. Percent is
- * escaped before every other character so decoding cannot collide with a
- * literal `%3A` name. The optional flag makes platform-specific behavior
- * directly testable without mutating `process.platform`.
- */
-export function encodeLocalVaultSegment(
-  segment: string,
-  win32: boolean = process.platform === "win32",
-): string {
-  if (!win32) return segment;
-
-  let encoded = "";
-  for (let index = 0; index < segment.length; index++) {
-    const char = segment[index]!;
-    const isTrailingDotOrSpace =
-      index === segment.length - 1 && (char === "." || char === " ");
-    const isDotSegment = (segment === "." || segment === "..") && index === 0;
-    const isReservedDeviceFirstChar = WIN32_DEVICE_NAME.test(segment) && index === 0;
-    if (
-      char === "%" ||
-      isWin32ReservedCharacter(char) ||
-      isTrailingDotOrSpace ||
-      isDotSegment ||
-      isReservedDeviceFirstChar
-    ) {
-      encoded += percentEscape(char);
-    } else {
-      encoded += char;
-    }
-  }
-  return encoded;
-}
-
-/** Decode one local filename segment back to its canonical vault-key form. */
-export function decodeLocalVaultSegment(
-  segment: string,
-  win32: boolean = process.platform === "win32",
-): string {
-  if (!win32) return segment;
-  return segment.replace(/%([0-9a-f]{2})/gi, (_whole, hex: string) =>
-    String.fromCharCode(Number.parseInt(hex, 16)),
-  );
-}
-
-/** Materialize a canonical slash-delimited vault key beneath a local root. */
-export function localPathForVaultKey(
-  root: string,
-  key: string,
-  win32: boolean = process.platform === "win32",
-): string {
-  return path.join(
-    root,
-    ...key.split("/").map((segment) => encodeLocalVaultSegment(segment, win32)),
-  );
-}
-
-/**
- * Turn a local, root-relative path back into its canonical vault key. This
- * recognizes legacy percent-encoded Windows materializations as well as the
- * current codec, so they converge on one remote/journal key instead of
- * creating duplicates.
- */
-export function vaultKeyForLocalPath(
-  root: string,
-  localPath: string,
-  win32: boolean = process.platform === "win32",
-): string {
-  return path
-    .relative(root, localPath)
-    .split(path.sep)
-    .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("/");
-}