@vibe-agent-toolkit/utils 0.2.0-rc.1 → 0.2.0-rc.3

package/README.md

@@ -23,10 +23,11 @@ The last two columns are the ones that matter when choosing. **"Resolves with ze
 | Subpath | Contents | Node builtins reached | Third-party | Resolves with zero deps installed? |
 |---|---|---|---|---|
 | `./path` | `safePath`, `toForwardSlash`, `toNfc`, `isAbsolutePath`, `isAbsoluteAnyPlatform`, `hasParentTraversalSegment`, `toAbsolutePath`, `getRelativePath`, `issueLocation` | `path` only | — | **yes** |
+| `./text` | `decodeTextContent` — the one bytes-to-text seam: BOM-announced UTF-8/UTF-16LE/UTF-16BE/UTF-32LE/UTF-32BE, BOM stripped, UTF-8 assumed otherwise; reports the encoding, whether it was a BOM fact or an assumption, and how many U+FFFD the decode substituted | **none** | — | **yes** |
 | `./zod` | `ZodTypeNames`, `getZodTypeName`, `isZodType`, `unwrapZodType`, `isZodOptional`, `isZodNullable` | **none** | — | **yes** |
 | `./glob` | `isGlob`, static base extraction, magic remainder | `path` only | — | **yes** |
-| `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `copyDirectory`, `fillSiblingNames`, `classifyFilenameCaseFrom`, `FsLookupCache` | `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
-| `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite` | `crypto`, `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
+| `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `copyDirectory`, `fillSiblingNames`, `classifyFilenameCaseFrom`, `FsLookupCache`, `readTextContent`, `readTextContentSync` | `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
+| `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite`, `removeScratchDir`, `symlinkCapability`, `createSymlink`, `createSymlinkAsync` | `crypto`, `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
 | `./asset` | `resolveAssetReference` — paths and npm bare specifiers | `fs`, `module`, `os`, `path`, `url` | — | **yes** |
 | `./yaml` | `updateYamlIn`, `verifyConfinedYamlEdit` — byte-surgical YAML edits | **none** | `yaml` | no — needs `yaml` |
 | `./template` | `renderTemplate` — cached Handlebars | **none** | `handlebars` | no — needs `handlebars` |
@@ -34,7 +35,7 @@ The last two columns are the ones that matter when choosing. **"Resolves with ze
 | `./git` | `gitFindRoot`, `gitLsFiles`, `isGitIgnored`, `loadGitignoreRules`, `GitTracker`, `parseGitUrl`, `isGitUrl`, `nonInteractiveGitOverrides` | `child_process`, `fs`, `os`, `path`, `url` | `ignore`, `which` | no — needs `which`, `ignore` |
 | `./crawl` | `crawlDirectory`, `crawlDirectorySync`, `NEVER_CRAWL_GLOBS`, `BUILD_OUTPUT_GLOBS` | `child_process`, `fs`, `os`, `path`, `url` | `picomatch`, `which` | no — needs `picomatch`, `which` |
 | `./project` | `findProjectRoot`, `findConfigFile`, `findNodeWorkspaceRoot`, `resetProjectRootCaches` | `fs`, `path` | — | **yes** |
-| `./eslint` | the 21 ESLint rules that enforce everything above — see [ESLint rules](#eslint-rules--vibe-agent-toolkitutilseslint) | **none** | — | **yes** |
+| `./eslint` | the 22 ESLint rules that enforce everything above — see [ESLint rules](#eslint-rules--vibe-agent-toolkitutilseslint) | **none** | — | **yes** |
 | `.` | every runtime entry above (not `./eslint`) | all of the above, plus `stream` | `handlebars`, `ignore`, `picomatch`, `which`, `yaml` | no — needs all of them |
 | `./package.json` | the manifest itself, for version reporting and resolution assertions | — | — | **yes** |
 
@@ -183,6 +184,8 @@ These return **OS-native** separators, because they resolve real filesystem iden
 
 - `setupAsyncTempDirSuite()` / `setupSyncTempDirSuite()` - per-suite temp directories with cleanup
 - `getTestOutputDir()` / `getTestOutputBase()` - isolated test output paths
+- `symlinkCapability()` - probes once (memoized per process) whether this host can create symlinks (Windows needs Developer Mode or `SeCreateSymbolicLinkPrivilege`), returning a `SymlinkCapability` token or `null`
+- `createSymlink()` / `createSymlinkAsync()` - the sanctioned way to create a symlink in test code; both require a `SymlinkCapability` from `symlinkCapability()`, so a test cannot reach the raw syscall without first proving the host supports it (or explicitly skipping via vitest's `skip()`)
 
 ### Project roots — `@vibe-agent-toolkit/utils` (barrel only)
 

package/dist/compare-code-units.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Host-independent string ordering, for sorts whose output is hashed or compared
+ * across machines.
+ *
+ * ## Why this is not `localeCompare`
+ *
+ * `sonarjs/no-alphabetical-sort` fires on a bare `strings.sort()` and its suggested fix is a
+ * `localeCompare` comparator. **That fix is wrong for anything whose order feeds a digest, a
+ * content key, a serialized document or a golden file.** Collation is locale-dependent, so two
+ * machines running the same code over the same corpus can order the same strings differently —
+ * destroying exactly the cross-run comparability those artifacts exist to provide. The rule only
+ * requires *a* comparator; this is the one to give it.
+ *
+ * Code-unit order is total, stable and machine-independent. It is not alphabetical in any human
+ * sense (uppercase sorts before lowercase, `10` before `2`), which is fine — callers using it are
+ * ordering bytes for a machine, not a list for a reader. Sort numbers numerically instead.
+ *
+ * This lives in `utils` because it had independently grown three identical private copies (in
+ * `resources`' projection digest and blob population, and in `claude-marketplace`' plugin extent)
+ * and a fourth was nearly written. Three copies of a "never use `localeCompare`" rule is three
+ * chances for someone to helpfully replace one of them.
+ *
+ * @param left - First string
+ * @param right - Second string
+ * @returns Negative, zero or positive per the `Array.prototype.sort` contract
+ */
+export declare function compareCodeUnits(left: string, right: string): number;
+//# sourceMappingURL=compare-code-units.d.ts.map

package/dist/compare-code-units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-code-units.d.ts","sourceRoot":"","sources":["../src/compare-code-units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKpE"}

package/dist/compare-code-units.js

@@ -0,0 +1,33 @@
+/**
+ * Host-independent string ordering, for sorts whose output is hashed or compared
+ * across machines.
+ *
+ * ## Why this is not `localeCompare`
+ *
+ * `sonarjs/no-alphabetical-sort` fires on a bare `strings.sort()` and its suggested fix is a
+ * `localeCompare` comparator. **That fix is wrong for anything whose order feeds a digest, a
+ * content key, a serialized document or a golden file.** Collation is locale-dependent, so two
+ * machines running the same code over the same corpus can order the same strings differently —
+ * destroying exactly the cross-run comparability those artifacts exist to provide. The rule only
+ * requires *a* comparator; this is the one to give it.
+ *
+ * Code-unit order is total, stable and machine-independent. It is not alphabetical in any human
+ * sense (uppercase sorts before lowercase, `10` before `2`), which is fine — callers using it are
+ * ordering bytes for a machine, not a list for a reader. Sort numbers numerically instead.
+ *
+ * This lives in `utils` because it had independently grown three identical private copies (in
+ * `resources`' projection digest and blob population, and in `claude-marketplace`' plugin extent)
+ * and a fourth was nearly written. Three copies of a "never use `localeCompare`" rule is three
+ * chances for someone to helpfully replace one of them.
+ *
+ * @param left - First string
+ * @param right - Second string
+ * @returns Negative, zero or positive per the `Array.prototype.sort` contract
+ */
+export function compareCodeUnits(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+}
+//# sourceMappingURL=compare-code-units.js.map

package/dist/compare-code-units.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-code-units.js","sourceRoot":"","sources":["../src/compare-code-units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,KAAa;IAC1D,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACnB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/B,CAAC"}