@wildwinter/toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @wildwinter/toolkit
+
+Small shared pieces of the **authoring tooling** behind
+[Storylet Studio](https://github.com/storylet-studio) and
+[Patter](https://patterkit.com): opaque ids, a stable hash, JSON5 source parsing,
+find/replace matching, and the archive guards.
+
+**Nothing here runs in a game.** This is the editor/CLI/pipeline side. The
+runtime language lives in [`@wildwinter/expr`](../expr), and unlike that package
+these pieces carry no shared semantics between the two product families: they
+are simply the same code, so a fix lands once.
+
+Each was found duplicated, almost but not exactly, across both families. That
+"almost" is the point. A zip-slip guard that is correct in two places today is
+one careless edit away from being correct in one, and nobody reads the diff of a
+file they believe is a copy.
+
+ESM + CJS + types. `json5` is the only dependency.
+
+```ts
+import { newId, slug, fnv32, parseSource, findMatcher } from "@wildwinter/toolkit";
+
+newId("scn");                     // "scn_8f3kq2z1"
+slug("The Long Dark!");           // "the-long-dark"
+fnv32("hello");                   // 1335831723
+parseSource('{ a: 1, /* ok */ }'); // JSON5, tolerating a byte-order mark
+findMatcher({ query: "a.b" });    // /a\.b/gi  (the query is escaped, not a pattern)
+```
+
+## Ids
+
+`newId(prefix = "", length = 8)` generates a stable, immutable, **opaque** id.
+It is never derived from content or position, so it survives moving, renaming
+and reordering the thing it names. The base-36 token is rejection-sampled, so
+every character is equally likely: a plain `byte % 36` over-weights the first
+four.
+
+`slug(name, fallback = "project")` is the human-facing counterpart, a url-ish
+label with a fallback for when nothing usable is left.
+
+## Hash
+
+`fnv32(text)` is FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit
+integer. A published, fixed algorithm, deliberately **not** cryptographic: it is
+for short stable handles and change detection, where the properties that matter
+are that it is the same everywhere and does not move between runs.
+
+## Source
+
+`parseSource(text)` parses JSON5, tolerating a leading byte-order mark, because
+editors on Windows add one and JSON5 will not accept it. Throws on malformed
+input.
+
+## Find
+
+`findMatcher({ query, caseSensitive?, wholeWord? })` builds the find/replace
+matcher, or `null` for an empty query. The query is **escaped**: somebody typing
+`a.b` means those three characters, not "a, anything, b". Always global, so
+every occurrence in a string is replaced rather than only the first.
+
+## Archive
+
+A separate, node-only entry point, because it imports `node:path`:
+
+```ts
+import {
+  isUnsafeEntry, escapesTarget, ARCHIVE_ENTRY_OPTS, ARCHIVE_GENERATE_OPTS,
+} from "@wildwinter/toolkit/archive";
+```
+
+`isUnsafeEntry(name)` is the cheap first pass on a name alone: absolute,
+drive-lettered, or climbing out with `..`. `escapesTarget(dir, name)` is the
+resolved check against a target directory. Together they are the zip-slip
+guard, and unpacking should refuse an entry either one rejects.
+
+`ARCHIVE_ENTRY_OPTS` and `ARCHIVE_GENERATE_OPTS` are the settings that make a
+pack **deterministic**: a fixed entry timestamp, no folder entries, no streaming.
+A pack of an unchanged project must be byte-identical to the last one, or every
+delivery churns. That is easy to leave out, and silent when you do.
+
+## Licence
+
+MIT

package/dist/archive.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+var path = require('path');
+
+// src/archive.ts
+function isUnsafeEntry(name) {
+  if (path.isAbsolute(name) || /^[a-zA-Z]:/.test(name)) return true;
+  const norm = path.normalize(name);
+  return norm === ".." || norm.startsWith(`..${path.sep}`) || norm.startsWith("../");
+}
+function escapesTarget(targetDir, name) {
+  const target = path.resolve(targetDir);
+  const full = path.resolve(path.join(target, name));
+  const rel = path.relative(target, full);
+  return rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel);
+}
+var ARCHIVE_ENTRY_DATE = /* @__PURE__ */ new Date("2000-01-01T00:00:00Z");
+var ARCHIVE_ENTRY_OPTS = { date: ARCHIVE_ENTRY_DATE, createFolders: false };
+var ARCHIVE_GENERATE_OPTS = {
+  type: "nodebuffer",
+  compression: "DEFLATE",
+  streamFiles: false
+};
+
+exports.ARCHIVE_ENTRY_DATE = ARCHIVE_ENTRY_DATE;
+exports.ARCHIVE_ENTRY_OPTS = ARCHIVE_ENTRY_OPTS;
+exports.ARCHIVE_GENERATE_OPTS = ARCHIVE_GENERATE_OPTS;
+exports.escapesTarget = escapesTarget;
+exports.isUnsafeEntry = isUnsafeEntry;
+//# sourceMappingURL=archive.cjs.map
+//# sourceMappingURL=archive.cjs.map

package/dist/archive.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/archive.ts"],"names":["isAbsolute","normalize","sep","resolve","join","relative"],"mappings":";;;;;AAwBO,SAAS,cAAc,IAAA,EAAuB;AACnD,EAAA,IAAIA,gBAAW,IAAI,CAAA,IAAK,aAAa,IAAA,CAAK,IAAI,GAAG,OAAO,IAAA;AACxD,EAAA,MAAM,IAAA,GAAOC,eAAU,IAAI,CAAA;AAC3B,EAAA,OAAO,IAAA,KAAS,IAAA,IAAQ,IAAA,CAAK,UAAA,CAAW,CAAA,EAAA,EAAKC,QAAG,CAAA,CAAE,CAAA,IAAK,IAAA,CAAK,UAAA,CAAW,KAAK,CAAA;AAC9E;AAWO,SAAS,aAAA,CAAc,WAAmB,IAAA,EAAuB;AACtE,EAAA,MAAM,MAAA,GAASC,aAAQ,SAAS,CAAA;AAChC,EAAA,MAAM,IAAA,GAAOA,YAAA,CAAQC,SAAA,CAAK,MAAA,EAAQ,IAAI,CAAC,CAAA;AACvC,EAAA,MAAM,GAAA,GAAMC,aAAA,CAAS,MAAA,EAAQ,IAAI,CAAA;AACjC,EAAA,OAAO,GAAA,KAAQ,EAAA,IAAM,GAAA,KAAQ,IAAA,IAAQ,GAAA,CAAI,UAAA,CAAW,CAAA,EAAA,EAAKH,QAAG,CAAA,CAAE,CAAA,IAAKF,eAAA,CAAW,GAAG,CAAA;AACnF;AAIO,IAAM,kBAAA,mBAAqB,IAAI,IAAA,CAAK,sBAAsB;AAI1D,IAAM,kBAAA,GAAqB,EAAE,IAAA,EAAM,kBAAA,EAAoB,eAAe,KAAA;AAItE,IAAM,qBAAA,GAAwB;AAAA,EACnC,IAAA,EAAM,YAAA;AAAA,EACN,WAAA,EAAa,SAAA;AAAA,EACb,WAAA,EAAa;AACf","file":"archive.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// Archive guards and settings, for the pack / unpack ops.\n//\n// Two concerns that both product families had solved, identically, in their own\n// copies:\n//\n//   - REFUSING A HOSTILE ENTRY. A zip can name `../../etc/passwd`, and writing\n//     it where it asks is the \"zip slip\" class of bug. Both guards below were\n//     correct in both families, which is the state BEFORE the drift rather than\n//     evidence there will not be one: a subtle weakening of one copy is a\n//     vulnerability nobody reads a diff for.\n//   - DETERMINISTIC BYTES. A pack of an unchanged project must be byte-identical\n//     to the last one, or every delivery churns. That needs a fixed entry\n//     timestamp and no folder entries, which is easy to leave out and silent\n//     when you do.\n//\n// Nothing here knows what is being packed.\n// ---------------------------------------------------------------------------\n\nimport { isAbsolute, join, normalize, relative, resolve, sep } from \"node:path\";\n\n/** An entry whose name refuses to be trusted at all: absolute, drive-lettered,\n *  or climbing out with `..`. A cheap first pass, used where a NAME is all that\n *  is available. */\nexport function isUnsafeEntry(name: string): boolean {\n  if (isAbsolute(name) || /^[a-zA-Z]:/.test(name)) return true;\n  const norm = normalize(name);\n  return norm === \"..\" || norm.startsWith(`..${sep}`) || norm.startsWith(\"../\");\n}\n\n/**\n * True when `join(targetDir, name)` would land outside `targetDir`.\n *\n * This is the guard that actually holds, and it is deliberately about the\n * RESOLVED PATH rather than the name: containment of a resolved path is a fact\n * about the write, where a judgement about a name is a guess about one. The\n * target itself counts as outside, because an entry that resolves to the\n * directory is not a file to write.\n */\nexport function escapesTarget(targetDir: string, name: string): boolean {\n  const target = resolve(targetDir);\n  const full = resolve(join(target, name));\n  const rel = relative(target, full);\n  return rel === \"\" || rel === \"..\" || rel.startsWith(`..${sep}`) || isAbsolute(rel);\n}\n\n/** The fixed timestamp every archive entry carries, so an unchanged project\n *  packs to the same bytes. Any constant would do; it must not be \"now\". */\nexport const ARCHIVE_ENTRY_DATE = new Date(\"2000-01-01T00:00:00Z\");\n\n/** Entry options for a reproducible archive: the fixed date, and no folder\n *  entries (whose presence and order vary by writer). */\nexport const ARCHIVE_ENTRY_OPTS = { date: ARCHIVE_ENTRY_DATE, createFolders: false } as const;\n\n/** Generation options for a reproducible archive. `streamFiles: false` matters:\n *  streamed entries carry data descriptors, which differ run to run. */\nexport const ARCHIVE_GENERATE_OPTS = {\n  type: \"nodebuffer\",\n  compression: \"DEFLATE\",\n  streamFiles: false,\n} as const;\n"]}

package/dist/archive.d.cts

@@ -0,0 +1,32 @@
+/** An entry whose name refuses to be trusted at all: absolute, drive-lettered,
+ *  or climbing out with `..`. A cheap first pass, used where a NAME is all that
+ *  is available. */
+declare function isUnsafeEntry(name: string): boolean;
+/**
+ * True when `join(targetDir, name)` would land outside `targetDir`.
+ *
+ * This is the guard that actually holds, and it is deliberately about the
+ * RESOLVED PATH rather than the name: containment of a resolved path is a fact
+ * about the write, where a judgement about a name is a guess about one. The
+ * target itself counts as outside, because an entry that resolves to the
+ * directory is not a file to write.
+ */
+declare function escapesTarget(targetDir: string, name: string): boolean;
+/** The fixed timestamp every archive entry carries, so an unchanged project
+ *  packs to the same bytes. Any constant would do; it must not be "now". */
+declare const ARCHIVE_ENTRY_DATE: Date;
+/** Entry options for a reproducible archive: the fixed date, and no folder
+ *  entries (whose presence and order vary by writer). */
+declare const ARCHIVE_ENTRY_OPTS: {
+    readonly date: Date;
+    readonly createFolders: false;
+};
+/** Generation options for a reproducible archive. `streamFiles: false` matters:
+ *  streamed entries carry data descriptors, which differ run to run. */
+declare const ARCHIVE_GENERATE_OPTS: {
+    readonly type: "nodebuffer";
+    readonly compression: "DEFLATE";
+    readonly streamFiles: false;
+};
+
+export { ARCHIVE_ENTRY_DATE, ARCHIVE_ENTRY_OPTS, ARCHIVE_GENERATE_OPTS, escapesTarget, isUnsafeEntry };

package/dist/archive.d.ts

@@ -0,0 +1,32 @@
+/** An entry whose name refuses to be trusted at all: absolute, drive-lettered,
+ *  or climbing out with `..`. A cheap first pass, used where a NAME is all that
+ *  is available. */
+declare function isUnsafeEntry(name: string): boolean;
+/**
+ * True when `join(targetDir, name)` would land outside `targetDir`.
+ *
+ * This is the guard that actually holds, and it is deliberately about the
+ * RESOLVED PATH rather than the name: containment of a resolved path is a fact
+ * about the write, where a judgement about a name is a guess about one. The
+ * target itself counts as outside, because an entry that resolves to the
+ * directory is not a file to write.
+ */
+declare function escapesTarget(targetDir: string, name: string): boolean;
+/** The fixed timestamp every archive entry carries, so an unchanged project
+ *  packs to the same bytes. Any constant would do; it must not be "now". */
+declare const ARCHIVE_ENTRY_DATE: Date;
+/** Entry options for a reproducible archive: the fixed date, and no folder
+ *  entries (whose presence and order vary by writer). */
+declare const ARCHIVE_ENTRY_OPTS: {
+    readonly date: Date;
+    readonly createFolders: false;
+};
+/** Generation options for a reproducible archive. `streamFiles: false` matters:
+ *  streamed entries carry data descriptors, which differ run to run. */
+declare const ARCHIVE_GENERATE_OPTS: {
+    readonly type: "nodebuffer";
+    readonly compression: "DEFLATE";
+    readonly streamFiles: false;
+};
+
+export { ARCHIVE_ENTRY_DATE, ARCHIVE_ENTRY_OPTS, ARCHIVE_GENERATE_OPTS, escapesTarget, isUnsafeEntry };

package/dist/archive.js

@@ -0,0 +1,25 @@
+import { isAbsolute, normalize, sep, resolve, join, relative } from 'path';
+
+// src/archive.ts
+function isUnsafeEntry(name) {
+  if (isAbsolute(name) || /^[a-zA-Z]:/.test(name)) return true;
+  const norm = normalize(name);
+  return norm === ".." || norm.startsWith(`..${sep}`) || norm.startsWith("../");
+}
+function escapesTarget(targetDir, name) {
+  const target = resolve(targetDir);
+  const full = resolve(join(target, name));
+  const rel = relative(target, full);
+  return rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+var ARCHIVE_ENTRY_DATE = /* @__PURE__ */ new Date("2000-01-01T00:00:00Z");
+var ARCHIVE_ENTRY_OPTS = { date: ARCHIVE_ENTRY_DATE, createFolders: false };
+var ARCHIVE_GENERATE_OPTS = {
+  type: "nodebuffer",
+  compression: "DEFLATE",
+  streamFiles: false
+};
+
+export { ARCHIVE_ENTRY_DATE, ARCHIVE_ENTRY_OPTS, ARCHIVE_GENERATE_OPTS, escapesTarget, isUnsafeEntry };
+//# sourceMappingURL=archive.js.map
+//# sourceMappingURL=archive.js.map

package/dist/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/archive.ts"],"names":[],"mappings":";;;AAwBO,SAAS,cAAc,IAAA,EAAuB;AACnD,EAAA,IAAI,WAAW,IAAI,CAAA,IAAK,aAAa,IAAA,CAAK,IAAI,GAAG,OAAO,IAAA;AACxD,EAAA,MAAM,IAAA,GAAO,UAAU,IAAI,CAAA;AAC3B,EAAA,OAAO,IAAA,KAAS,IAAA,IAAQ,IAAA,CAAK,UAAA,CAAW,CAAA,EAAA,EAAK,GAAG,CAAA,CAAE,CAAA,IAAK,IAAA,CAAK,UAAA,CAAW,KAAK,CAAA;AAC9E;AAWO,SAAS,aAAA,CAAc,WAAmB,IAAA,EAAuB;AACtE,EAAA,MAAM,MAAA,GAAS,QAAQ,SAAS,CAAA;AAChC,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,IAAA,CAAK,MAAA,EAAQ,IAAI,CAAC,CAAA;AACvC,EAAA,MAAM,GAAA,GAAM,QAAA,CAAS,MAAA,EAAQ,IAAI,CAAA;AACjC,EAAA,OAAO,GAAA,KAAQ,EAAA,IAAM,GAAA,KAAQ,IAAA,IAAQ,GAAA,CAAI,UAAA,CAAW,CAAA,EAAA,EAAK,GAAG,CAAA,CAAE,CAAA,IAAK,UAAA,CAAW,GAAG,CAAA;AACnF;AAIO,IAAM,kBAAA,mBAAqB,IAAI,IAAA,CAAK,sBAAsB;AAI1D,IAAM,kBAAA,GAAqB,EAAE,IAAA,EAAM,kBAAA,EAAoB,eAAe,KAAA;AAItE,IAAM,qBAAA,GAAwB;AAAA,EACnC,IAAA,EAAM,YAAA;AAAA,EACN,WAAA,EAAa,SAAA;AAAA,EACb,WAAA,EAAa;AACf","file":"archive.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Archive guards and settings, for the pack / unpack ops.\n//\n// Two concerns that both product families had solved, identically, in their own\n// copies:\n//\n//   - REFUSING A HOSTILE ENTRY. A zip can name `../../etc/passwd`, and writing\n//     it where it asks is the \"zip slip\" class of bug. Both guards below were\n//     correct in both families, which is the state BEFORE the drift rather than\n//     evidence there will not be one: a subtle weakening of one copy is a\n//     vulnerability nobody reads a diff for.\n//   - DETERMINISTIC BYTES. A pack of an unchanged project must be byte-identical\n//     to the last one, or every delivery churns. That needs a fixed entry\n//     timestamp and no folder entries, which is easy to leave out and silent\n//     when you do.\n//\n// Nothing here knows what is being packed.\n// ---------------------------------------------------------------------------\n\nimport { isAbsolute, join, normalize, relative, resolve, sep } from \"node:path\";\n\n/** An entry whose name refuses to be trusted at all: absolute, drive-lettered,\n *  or climbing out with `..`. A cheap first pass, used where a NAME is all that\n *  is available. */\nexport function isUnsafeEntry(name: string): boolean {\n  if (isAbsolute(name) || /^[a-zA-Z]:/.test(name)) return true;\n  const norm = normalize(name);\n  return norm === \"..\" || norm.startsWith(`..${sep}`) || norm.startsWith(\"../\");\n}\n\n/**\n * True when `join(targetDir, name)` would land outside `targetDir`.\n *\n * This is the guard that actually holds, and it is deliberately about the\n * RESOLVED PATH rather than the name: containment of a resolved path is a fact\n * about the write, where a judgement about a name is a guess about one. The\n * target itself counts as outside, because an entry that resolves to the\n * directory is not a file to write.\n */\nexport function escapesTarget(targetDir: string, name: string): boolean {\n  const target = resolve(targetDir);\n  const full = resolve(join(target, name));\n  const rel = relative(target, full);\n  return rel === \"\" || rel === \"..\" || rel.startsWith(`..${sep}`) || isAbsolute(rel);\n}\n\n/** The fixed timestamp every archive entry carries, so an unchanged project\n *  packs to the same bytes. Any constant would do; it must not be \"now\". */\nexport const ARCHIVE_ENTRY_DATE = new Date(\"2000-01-01T00:00:00Z\");\n\n/** Entry options for a reproducible archive: the fixed date, and no folder\n *  entries (whose presence and order vary by writer). */\nexport const ARCHIVE_ENTRY_OPTS = { date: ARCHIVE_ENTRY_DATE, createFolders: false } as const;\n\n/** Generation options for a reproducible archive. `streamFiles: false` matters:\n *  streamed entries carry data descriptors, which differ run to run. */\nexport const ARCHIVE_GENERATE_OPTS = {\n  type: \"nodebuffer\",\n  compression: \"DEFLATE\",\n  streamFiles: false,\n} as const;\n"]}

package/dist/index.cjs

@@ -0,0 +1,58 @@
+'use strict';
+
+var JSON5 = require('json5');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var JSON5__default = /*#__PURE__*/_interopDefault(JSON5);
+
+// src/ids.ts
+var ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+function newId(prefix = "", length = 8) {
+  const limit = 256 - 256 % ALPHABET.length;
+  let token = "";
+  while (token.length < length) {
+    const bytes = new Uint8Array(length * 2);
+    globalThis.crypto.getRandomValues(bytes);
+    for (const b of bytes) {
+      if (b >= limit) continue;
+      token += ALPHABET[b % ALPHABET.length];
+      if (token.length === length) break;
+    }
+  }
+  return prefix ? `${prefix}_${token}` : token;
+}
+function slug(name, fallback = "project") {
+  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return s || fallback;
+}
+
+// src/hash.ts
+function fnv32(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function parseSource(text) {
+  const body = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+  return JSON5__default.default.parse(body);
+}
+
+// src/find.ts
+function findMatcher(opts) {
+  if (!opts.query) return null;
+  const esc = opts.query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const body = opts.wholeWord ? `\\b${esc}\\b` : esc;
+  return new RegExp(body, opts.caseSensitive ? "g" : "gi");
+}
+
+exports.findMatcher = findMatcher;
+exports.fnv32 = fnv32;
+exports.newId = newId;
+exports.parseSource = parseSource;
+exports.slug = slug;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ids.ts","../src/hash.ts","../src/source.ts","../src/find.ts"],"names":["JSON5"],"mappings":";;;;;;;;;AASA,IAAM,QAAA,GAAW,sCAAA;AAGV,SAAS,KAAA,CAAM,MAAA,GAAS,EAAA,EAAI,MAAA,GAAS,CAAA,EAAW;AAGrD,EAAA,MAAM,KAAA,GAAQ,GAAA,GAAO,GAAA,GAAM,QAAA,CAAS,MAAA;AACpC,EAAA,IAAI,KAAA,GAAQ,EAAA;AACZ,EAAA,OAAO,KAAA,CAAM,SAAS,MAAA,EAAQ;AAC5B,IAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,MAAA,GAAS,CAAC,CAAA;AACvC,IAAA,UAAA,CAAW,MAAA,CAAO,gBAAgB,KAAK,CAAA;AACvC,IAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,MAAA,IAAI,KAAK,KAAA,EAAO;AAChB,MAAA,KAAA,IAAS,QAAA,CAAS,CAAA,GAAI,QAAA,CAAS,MAAM,CAAA;AACrC,MAAA,IAAI,KAAA,CAAM,WAAW,MAAA,EAAQ;AAAA,IAC/B;AAAA,EACF;AACA,EAAA,OAAO,MAAA,GAAS,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,KAAK,CAAA,CAAA,GAAK,KAAA;AACzC;AAGO,SAAS,IAAA,CAAK,IAAA,EAAc,QAAA,GAAW,SAAA,EAAmB;AAC/D,EAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAA,EAAK,CAAE,WAAA,EAAY,CAAE,OAAA,CAAQ,aAAA,EAAe,GAAG,CAAA,CAAE,OAAA,CAAQ,UAAA,EAAY,EAAE,CAAA;AACtF,EAAA,OAAO,CAAA,IAAK,QAAA;AACd;;;ACxBO,SAAS,MAAM,KAAA,EAAuB;AAC3C,EAAA,IAAI,CAAA,GAAI,UAAA;AACR,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,QAAQ,CAAA,EAAA,EAAK;AACrC,IAAA,CAAA,IAAK,KAAA,CAAM,WAAW,CAAC,CAAA;AACvB,IAAA,CAAA,GAAI,IAAA,CAAK,IAAA,CAAK,CAAA,EAAG,QAAU,CAAA;AAAA,EAC7B;AACA,EAAA,OAAO,CAAA,KAAM,CAAA;AACf;ACLO,SAAS,YAAY,IAAA,EAAuB;AACjD,EAAA,MAAM,IAAA,GAAO,KAAK,UAAA,CAAW,CAAC,MAAM,KAAA,GAAS,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA,GAAI,IAAA;AAC7D,EAAA,OAAOA,sBAAA,CAAM,MAAM,IAAI,CAAA;AACzB;;;ACGO,SAAS,YAAY,IAAA,EAAkC;AAC5D,EAAA,IAAI,CAAC,IAAA,CAAK,KAAA,EAAO,OAAO,IAAA;AACxB,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,KAAA,CAAM,OAAA,CAAQ,uBAAuB,MAAM,CAAA;AAC5D,EAAA,MAAM,IAAA,GAAO,IAAA,CAAK,SAAA,GAAY,CAAA,GAAA,EAAM,GAAG,CAAA,GAAA,CAAA,GAAQ,GAAA;AAC/C,EAAA,OAAO,IAAI,MAAA,CAAO,IAAA,EAAM,IAAA,CAAK,aAAA,GAAgB,MAAM,IAAI,CAAA;AACzD","file":"index.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// Stable, immutable, opaque ids.\n//\n// Generated at creation, never derived from content or position, so an id\n// survives moving, renaming and reordering the thing it names. A short,\n// collision-resistant base-36 token with an optional type prefix that aids\n// debugging but carries no meaning.\n// ---------------------------------------------------------------------------\n\nconst ALPHABET = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\n/** Generate a new opaque id, e.g. `newId(\"scn\") -> \"scn_8f3kq2z1\"`. */\nexport function newId(prefix = \"\", length = 8): string {\n  // Rejection-sample so every alphabet character is equally likely: a plain\n  // `byte % 36` over-weights the first four characters.\n  const limit = 256 - (256 % ALPHABET.length); // 252\n  let token = \"\";\n  while (token.length < length) {\n    const bytes = new Uint8Array(length * 2);\n    globalThis.crypto.getRandomValues(bytes);\n    for (const b of bytes) {\n      if (b >= limit) continue;\n      token += ALPHABET[b % ALPHABET.length];\n      if (token.length === length) break;\n    }\n  }\n  return prefix ? `${prefix}_${token}` : token;\n}\n\n/** A url-ish slug from a human label; `\"project\"` when nothing usable is left. */\nexport function slug(name: string, fallback = \"project\"): string {\n  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n  return s || fallback;\n}\n","// ---------------------------------------------------------------------------\n// FNV-1a, 32-bit.\n//\n// A published, fixed algorithm. Not cryptographic: it is for short stable\n// handles and change detection, where the properties that matter are that it is\n// the same everywhere and does not move between runs.\n// ---------------------------------------------------------------------------\n\n/** FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit integer. */\nexport function fnv32(input: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n","// ---------------------------------------------------------------------------\n// Reading authored source files.\n// ---------------------------------------------------------------------------\n\nimport JSON5 from \"json5\";\n\n/**\n * Parse JSON5 source text. A leading byte-order mark is tolerated, because\n * editors on Windows add one and JSON5 will not accept it. Throws on malformed\n * input.\n */\nexport function parseSource(text: string): unknown {\n  const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n  return JSON5.parse(body);\n}\n","// ---------------------------------------------------------------------------\n// Find and replace over authored text.\n// ---------------------------------------------------------------------------\n\nexport interface FindOptions {\n  query: string;\n  caseSensitive?: boolean;\n  wholeWord?: boolean;\n}\n\n/**\n * Build the find matcher, or null for an empty query. Global, so every\n * occurrence in a string is replaced rather than only the first.\n *\n * The query is escaped: a person typing `a.b` means those three characters, not\n * \"a, anything, b\".\n */\nexport function findMatcher(opts: FindOptions): RegExp | null {\n  if (!opts.query) return null;\n  const esc = opts.query.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n  const body = opts.wholeWord ? `\\\\b${esc}\\\\b` : esc;\n  return new RegExp(body, opts.caseSensitive ? \"g\" : \"gi\");\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+/** Generate a new opaque id, e.g. `newId("scn") -> "scn_8f3kq2z1"`. */
+declare function newId(prefix?: string, length?: number): string;
+/** A url-ish slug from a human label; `"project"` when nothing usable is left. */
+declare function slug(name: string, fallback?: string): string;
+
+/** FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit integer. */
+declare function fnv32(input: string): number;
+
+/**
+ * Parse JSON5 source text. A leading byte-order mark is tolerated, because
+ * editors on Windows add one and JSON5 will not accept it. Throws on malformed
+ * input.
+ */
+declare function parseSource(text: string): unknown;
+
+interface FindOptions {
+    query: string;
+    caseSensitive?: boolean;
+    wholeWord?: boolean;
+}
+/**
+ * Build the find matcher, or null for an empty query. Global, so every
+ * occurrence in a string is replaced rather than only the first.
+ *
+ * The query is escaped: a person typing `a.b` means those three characters, not
+ * "a, anything, b".
+ */
+declare function findMatcher(opts: FindOptions): RegExp | null;
+
+export { type FindOptions, findMatcher, fnv32, newId, parseSource, slug };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/** Generate a new opaque id, e.g. `newId("scn") -> "scn_8f3kq2z1"`. */
+declare function newId(prefix?: string, length?: number): string;
+/** A url-ish slug from a human label; `"project"` when nothing usable is left. */
+declare function slug(name: string, fallback?: string): string;
+
+/** FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit integer. */
+declare function fnv32(input: string): number;
+
+/**
+ * Parse JSON5 source text. A leading byte-order mark is tolerated, because
+ * editors on Windows add one and JSON5 will not accept it. Throws on malformed
+ * input.
+ */
+declare function parseSource(text: string): unknown;
+
+interface FindOptions {
+    query: string;
+    caseSensitive?: boolean;
+    wholeWord?: boolean;
+}
+/**
+ * Build the find matcher, or null for an empty query. Global, so every
+ * occurrence in a string is replaced rather than only the first.
+ *
+ * The query is escaped: a person typing `a.b` means those three characters, not
+ * "a, anything, b".
+ */
+declare function findMatcher(opts: FindOptions): RegExp | null;
+
+export { type FindOptions, findMatcher, fnv32, newId, parseSource, slug };

package/dist/index.js

@@ -0,0 +1,48 @@
+import JSON5 from 'json5';
+
+// src/ids.ts
+var ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+function newId(prefix = "", length = 8) {
+  const limit = 256 - 256 % ALPHABET.length;
+  let token = "";
+  while (token.length < length) {
+    const bytes = new Uint8Array(length * 2);
+    globalThis.crypto.getRandomValues(bytes);
+    for (const b of bytes) {
+      if (b >= limit) continue;
+      token += ALPHABET[b % ALPHABET.length];
+      if (token.length === length) break;
+    }
+  }
+  return prefix ? `${prefix}_${token}` : token;
+}
+function slug(name, fallback = "project") {
+  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return s || fallback;
+}
+
+// src/hash.ts
+function fnv32(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function parseSource(text) {
+  const body = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+  return JSON5.parse(body);
+}
+
+// src/find.ts
+function findMatcher(opts) {
+  if (!opts.query) return null;
+  const esc = opts.query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const body = opts.wholeWord ? `\\b${esc}\\b` : esc;
+  return new RegExp(body, opts.caseSensitive ? "g" : "gi");
+}
+
+export { findMatcher, fnv32, newId, parseSource, slug };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ids.ts","../src/hash.ts","../src/source.ts","../src/find.ts"],"names":[],"mappings":";;;AASA,IAAM,QAAA,GAAW,sCAAA;AAGV,SAAS,KAAA,CAAM,MAAA,GAAS,EAAA,EAAI,MAAA,GAAS,CAAA,EAAW;AAGrD,EAAA,MAAM,KAAA,GAAQ,GAAA,GAAO,GAAA,GAAM,QAAA,CAAS,MAAA;AACpC,EAAA,IAAI,KAAA,GAAQ,EAAA;AACZ,EAAA,OAAO,KAAA,CAAM,SAAS,MAAA,EAAQ;AAC5B,IAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,MAAA,GAAS,CAAC,CAAA;AACvC,IAAA,UAAA,CAAW,MAAA,CAAO,gBAAgB,KAAK,CAAA;AACvC,IAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,MAAA,IAAI,KAAK,KAAA,EAAO;AAChB,MAAA,KAAA,IAAS,QAAA,CAAS,CAAA,GAAI,QAAA,CAAS,MAAM,CAAA;AACrC,MAAA,IAAI,KAAA,CAAM,WAAW,MAAA,EAAQ;AAAA,IAC/B;AAAA,EACF;AACA,EAAA,OAAO,MAAA,GAAS,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,KAAK,CAAA,CAAA,GAAK,KAAA;AACzC;AAGO,SAAS,IAAA,CAAK,IAAA,EAAc,QAAA,GAAW,SAAA,EAAmB;AAC/D,EAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAA,EAAK,CAAE,WAAA,EAAY,CAAE,OAAA,CAAQ,aAAA,EAAe,GAAG,CAAA,CAAE,OAAA,CAAQ,UAAA,EAAY,EAAE,CAAA;AACtF,EAAA,OAAO,CAAA,IAAK,QAAA;AACd;;;ACxBO,SAAS,MAAM,KAAA,EAAuB;AAC3C,EAAA,IAAI,CAAA,GAAI,UAAA;AACR,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,QAAQ,CAAA,EAAA,EAAK;AACrC,IAAA,CAAA,IAAK,KAAA,CAAM,WAAW,CAAC,CAAA;AACvB,IAAA,CAAA,GAAI,IAAA,CAAK,IAAA,CAAK,CAAA,EAAG,QAAU,CAAA;AAAA,EAC7B;AACA,EAAA,OAAO,CAAA,KAAM,CAAA;AACf;ACLO,SAAS,YAAY,IAAA,EAAuB;AACjD,EAAA,MAAM,IAAA,GAAO,KAAK,UAAA,CAAW,CAAC,MAAM,KAAA,GAAS,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA,GAAI,IAAA;AAC7D,EAAA,OAAO,KAAA,CAAM,MAAM,IAAI,CAAA;AACzB;;;ACGO,SAAS,YAAY,IAAA,EAAkC;AAC5D,EAAA,IAAI,CAAC,IAAA,CAAK,KAAA,EAAO,OAAO,IAAA;AACxB,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,KAAA,CAAM,OAAA,CAAQ,uBAAuB,MAAM,CAAA;AAC5D,EAAA,MAAM,IAAA,GAAO,IAAA,CAAK,SAAA,GAAY,CAAA,GAAA,EAAM,GAAG,CAAA,GAAA,CAAA,GAAQ,GAAA;AAC/C,EAAA,OAAO,IAAI,MAAA,CAAO,IAAA,EAAM,IAAA,CAAK,aAAA,GAAgB,MAAM,IAAI,CAAA;AACzD","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Stable, immutable, opaque ids.\n//\n// Generated at creation, never derived from content or position, so an id\n// survives moving, renaming and reordering the thing it names. A short,\n// collision-resistant base-36 token with an optional type prefix that aids\n// debugging but carries no meaning.\n// ---------------------------------------------------------------------------\n\nconst ALPHABET = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\n/** Generate a new opaque id, e.g. `newId(\"scn\") -> \"scn_8f3kq2z1\"`. */\nexport function newId(prefix = \"\", length = 8): string {\n  // Rejection-sample so every alphabet character is equally likely: a plain\n  // `byte % 36` over-weights the first four characters.\n  const limit = 256 - (256 % ALPHABET.length); // 252\n  let token = \"\";\n  while (token.length < length) {\n    const bytes = new Uint8Array(length * 2);\n    globalThis.crypto.getRandomValues(bytes);\n    for (const b of bytes) {\n      if (b >= limit) continue;\n      token += ALPHABET[b % ALPHABET.length];\n      if (token.length === length) break;\n    }\n  }\n  return prefix ? `${prefix}_${token}` : token;\n}\n\n/** A url-ish slug from a human label; `\"project\"` when nothing usable is left. */\nexport function slug(name: string, fallback = \"project\"): string {\n  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n  return s || fallback;\n}\n","// ---------------------------------------------------------------------------\n// FNV-1a, 32-bit.\n//\n// A published, fixed algorithm. Not cryptographic: it is for short stable\n// handles and change detection, where the properties that matter are that it is\n// the same everywhere and does not move between runs.\n// ---------------------------------------------------------------------------\n\n/** FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit integer. */\nexport function fnv32(input: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n","// ---------------------------------------------------------------------------\n// Reading authored source files.\n// ---------------------------------------------------------------------------\n\nimport JSON5 from \"json5\";\n\n/**\n * Parse JSON5 source text. A leading byte-order mark is tolerated, because\n * editors on Windows add one and JSON5 will not accept it. Throws on malformed\n * input.\n */\nexport function parseSource(text: string): unknown {\n  const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n  return JSON5.parse(body);\n}\n","// ---------------------------------------------------------------------------\n// Find and replace over authored text.\n// ---------------------------------------------------------------------------\n\nexport interface FindOptions {\n  query: string;\n  caseSensitive?: boolean;\n  wholeWord?: boolean;\n}\n\n/**\n * Build the find matcher, or null for an empty query. Global, so every\n * occurrence in a string is replaced rather than only the first.\n *\n * The query is escaped: a person typing `a.b` means those three characters, not\n * \"a, anything, b\".\n */\nexport function findMatcher(opts: FindOptions): RegExp | null {\n  if (!opts.query) return null;\n  const esc = opts.query.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n  const body = opts.wholeWord ? `\\\\b${esc}\\\\b` : esc;\n  return new RegExp(body, opts.caseSensitive ? \"g\" : \"gi\");\n}\n"]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@wildwinter/toolkit",
+  "version": "0.1.0",
+  "description": "Small shared pieces of the authoring tooling: opaque ids, a stable hash, JSON5 source parsing, find/replace matching, and the archive guards. Nothing here runs in a game.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ian Thomas",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wildwinter/expr.git",
+    "directory": "packages/toolkit"
+  },
+  "keywords": [
+    "ids",
+    "hash",
+    "json5",
+    "zip",
+    "tooling"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./archive": {
+      "types": "./dist/archive.d.ts",
+      "import": "./dist/archive.js",
+      "require": "./dist/archive.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "json5": "^2.2.3"
+  }
+}