@valfuse-node/assets 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 valfuse-node contributors
+
+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

@@ -1,3 +1,247 @@
-# Temporary Holding Version
+# @valfuse-node/assets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate a typed TypeScript registry for static assets. Directory names and
+file names become nested keys, and each leaf contains the asset's public URL.
+
+```bash
+npm install --save-dev @valfuse-node/assets
+```
+
+Requires **Node.js 22 or newer** to run the generator. The generated module is
+plain TypeScript and has no runtime dependency on this package.
+
+The package declares `engines.node >=22`. Install it as a development
+dependency when you generate the registry during development or CI.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Generated names and paths](#generated-names-and-paths)
+- [Programmatic API](#programmatic-api)
+- [Troubleshooting](#troubleshooting)
+- [Scope](#scope)
+- [Release history](#release-history)
+- [Support](#support)
+- [License](#license)
+
+## Quick start
+
+Place files under `public/assets`:
+
+```text
+public/assets/
+├── images/
+│   ├── company-logo.svg
+│   └── profile/avatar.png
+└── icons/search.svg
+```
+
+Create `valfuse-assets.yaml` in the project root:
+
+```yaml
+input_dir: public/assets
+output_file: src/assets/assets.ts
+base_path: /assets
+```
+
+Run `npx valfuse-assets`. It generates `src/assets/assets.ts`:
+
+```ts
+import { assets } from "./assets/assets";
+
+assets.images.companyLogo; // "/assets/images/company-logo.svg"
+assets.images.profile.avatar; // "/assets/images/profile/avatar.png"
+assets.icons.search; // "/assets/icons/search.svg"
+```
+
+The generator also exports `AssetPath`, a union of all generated URL strings:
+
+```ts
+import { assets, type AssetPath } from "./assets/assets";
+
+const logo: AssetPath = assets.images.companyLogo;
+```
+
+The path values work with React, Vue, HTML, and other browser code that accepts
+URLs. Put assets in the framework's public/static directory so the framework
+copies them to the matching URL at build time.
+
+For example, in a React component:
+
+```tsx
+import { assets } from "./assets/assets";
+
+export function CompanyLogo() {
+  return <img src={assets.images.companyLogo} alt="Company" />;
+}
+```
+
+The generated registry contains URL strings only. Keep the source files in the
+public directory and make sure the configured `base_path` matches the URL path
+your server or CDN uses to serve that directory.
+
+## Configuration
+
+The CLI reads `valfuse-assets.yaml` from the current working directory, matching
+the config-file convention used by the localization CLI:
+
+```yaml
+input_dir: public/media
+output_file: src/assets/assets.ts
+base_path: /media
+```
+
+Relative file paths in this config are resolved from the current working
+directory; absolute file paths are also accepted. The `base_path` is the URL
+prefix that serves the contents of `input_dir`; it can be a root-relative path
+such as `/media` or an absolute HTTP(S) URL for a CDN.
+Each discovered file's path beneath `input_dir` is appended to this prefix.
+Input and output paths are resolved from the current working directory. The
+CLI accepts only these snake_case YAML keys; unknown keys, empty values, an
+invalid URL prefix, or an output filename without a `.ts` extension are errors.
+
+The default values are:
+
+| Option        | Default                | Purpose                                    |
+| ------------- | ---------------------- | ------------------------------------------ |
+| `input_dir`   | `public/assets`        | Directory tree to scan                     |
+| `output_file` | `src/assets/assets.ts` | Generated TypeScript module                |
+| `base_path`   | `/assets`              | Public URL prefix for files in `input_dir` |
+
+Pass another config file with `--config`:
+
+```bash
+npx valfuse-assets --config config/valfuse-assets.yaml
+```
+
+Use `--check` in CI to fail when the generated module is missing or stale. It
+does not write files:
+
+```bash
+npx valfuse-assets --check
+npx valfuse-assets --help
+```
+
+| Option            | Behavior                                      |
+| ----------------- | --------------------------------------------- |
+| `--config <file>` | Read another YAML config file                 |
+| `--check`         | Fail if the generated module is missing/stale |
+| `--help`, `-h`    | Print CLI usage and defaults                  |
+
+For repeatable project commands, add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "assets:generate": "valfuse-assets",
+    "assets:check": "valfuse-assets --check"
+  }
+}
+```
+
+Run `npm run assets:generate` after changing files under the input directory.
+Run `npm run assets:check` in CI to ensure the committed generated registry is
+current. The command does not copy, transform, or fingerprint source files.
+
+## Generated names and paths
+
+- Nested folders remain nested object keys.
+- File extensions are removed from keys: `company-logo.svg` becomes
+  `companyLogo`.
+- Folder and file names are converted to lower camel case, including names that
+  already use camel case. A leading number is prefixed with `_`.
+- URL segments are percent-encoded while the generated keys use readable names.
+- Output is sorted deterministically, and unchanged output files are not
+  rewritten.
+- Name collisions after normalization produce an error instead of silently
+  replacing an asset.
+- Symlinks, special filesystem entries, `.DS_Store`, `Thumbs.db`, and
+  `desktop.ini` are skipped.
+
+## Programmatic API
+
+The Node.js API is also available from the explicit
+**@valfuse-node/core/assets** subpath. It is not loaded from the core root
+import; use the standalone **@valfuse-node/assets** package when you only need
+the CLI.
+
+The generator can also be called from a Node.js build script:
+
+```ts
+import { generateAssets } from "@valfuse-node/assets";
+
+await generateAssets({
+  config: {
+    inputDir: "public/assets",
+    outputFile: "src/assets/assets.ts",
+    basePath: "/assets",
+  },
+});
+```
+
+`GenerateAssetsOptions` accepts an optional `cwd`, partial camelCase `config`,
+and `check` flag. The equivalent of the default config is:
+
+```ts
+{
+  inputDir: "public/assets",
+  outputFile: "src/assets/assets.ts",
+  basePath: "/assets",
+}
+```
+
+The package entry exports `generateAssets` and
+`DEFAULT_ASSET_GENERATOR_CONFIG`. Its public types are
+`AssetGeneratorConfig`, `AssetGeneratorConfigInput`, `GenerateAssetsOptions`,
+and `GenerateAssetsResult`.
+
+Pass `check: true` to check generated output without writing it. On success,
+`generateAssets` returns `GenerateAssetsResult`:
+
+```ts
+{
+  assetCount: number;
+  outputFile: string; // absolute path
+  changed: boolean;
+}
+```
+
+The function rejects missing or invalid input directories, invalid config, and
+asset-name collisions with an `Error`. In check mode, it also throws when the
+generated file is missing or stale.
+
+## Troubleshooting
+
+- **Input directory not found:** run the CLI from the project root or set
+  `cwd` in the API call; configured paths are relative to that directory.
+- **Two files map to the same TypeScript key:** rename one path segment. For
+  example, names that normalize to the same lower-camel-case key cannot share
+  the registry.
+- **A generated URL returns 404:** compare `base_path` with the actual public
+  URL for the configured input directory. The generator does not move files.
+- **CI reports stale output:** run `npm run assets:generate` and commit the
+  updated generated module.
+
+## Scope
+
+This package generates a typed registry of static public URLs. It does not
+import files into Vite/Webpack bundles, transform image files, or generate
+image, SVG, font, or color helper APIs. For bundled assets, use your bundler's
+asset import or `new URL(..., import.meta.url)` behavior instead.
+
+## Release history
+
+See the [monorepo changelog](https://github.com/alpinnz/valfuse-node/blob/master/CHANGELOG.md).
+
+## Support
+
+For usage questions, bug reports, and feature requests, see the
+[project support guide](https://github.com/alpinnz/valfuse-node/blob/master/SUPPORT.md).
+For security reports, follow the
+[security policy](https://github.com/alpinnz/valfuse-node/blob/master/SECURITY.md).
+Do not use public issues for security reports.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli/index.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { readFile as readFile2 } from "fs/promises";
+import { relative as relative2, resolve as resolve2 } from "path";
+import YAML from "yaml";
+
+// src/generator.ts
+import { lstat, mkdir, readFile, readdir, writeFile } from "fs/promises";
+import { dirname, extname, relative, resolve } from "path";
+var DEFAULT_ASSET_GENERATOR_CONFIG = Object.freeze({
+  inputDir: "public/assets",
+  outputFile: "src/assets/assets.ts",
+  basePath: "/assets"
+});
+var IGNORED_SYSTEM_FILES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+async function generateAssets(options = {}) {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const config = normalizeConfig(options.config);
+  const inputDir = resolve(cwd, config.inputDir);
+  const outputFile = resolve(cwd, config.outputFile);
+  let inputStats;
+  try {
+    inputStats = await lstat(inputDir);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      throw new Error(`Asset input directory not found: ${inputDir}`, { cause: error });
+    }
+    throw error;
+  }
+  if (!inputStats.isDirectory()) {
+    throw new Error(`Asset input must be a directory and cannot be a symlink: ${inputDir}`);
+  }
+  const files = await collectAssetFiles(inputDir, outputFile);
+  const tree = createAssetTree(files, config.basePath);
+  const source = renderAssetModule(tree);
+  const existingSource = await readExistingFile(outputFile);
+  const changed = existingSource !== source;
+  if (options.check) {
+    if (changed) {
+      throw new Error(
+        `Generated asset registry is missing or out of date: ${relative(cwd, outputFile)}. Run "npx valfuse-assets" to regenerate it.`
+      );
+    }
+    return { assetCount: files.length, outputFile, changed: false };
+  }
+  if (changed) {
+    await mkdir(dirname(outputFile), { recursive: true });
+    await writeFile(outputFile, source, "utf8");
+  }
+  return { assetCount: files.length, outputFile, changed };
+}
+function normalizeConfig(input = {}) {
+  const config = { ...DEFAULT_ASSET_GENERATOR_CONFIG, ...input };
+  for (const [key, value] of Object.entries(config)) {
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new Error(`Config "${key}" must be a non-empty string.`);
+    }
+  }
+  if (/[?#\\]/.test(config.basePath)) {
+    throw new Error('Config "basePath" cannot contain a query, fragment, or backslash.');
+  }
+  if (!config.basePath.startsWith("/") && !/^https?:\/\//i.test(config.basePath)) {
+    throw new Error('Config "basePath" must start with "/" or be an absolute HTTP(S) URL.');
+  }
+  if (/^https?:\/\//i.test(config.basePath)) {
+    const url = new URL(config.basePath);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error('Config "basePath" must use HTTP or HTTPS.');
+    }
+  }
+  if (extname(config.outputFile).toLowerCase() !== ".ts") {
+    throw new Error('Config "outputFile" must have a .ts extension.');
+  }
+  return config;
+}
+async function collectAssetFiles(inputDir, outputFile) {
+  const files = [];
+  async function visit(directory, relativeDirectory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => compareNames(left.name, right.name));
+    for (const entry of entries) {
+      if (IGNORED_SYSTEM_FILES.has(entry.name)) continue;
+      const absolutePath = resolve(directory, entry.name);
+      const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await visit(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.isFile() || pathsEqual(absolutePath, outputFile)) continue;
+      files.push({ relativePath });
+    }
+  }
+  await visit(inputDir, "");
+  return files;
+}
+function createAssetTree(files, basePath) {
+  const root = { originalName: "", children: /* @__PURE__ */ new Map() };
+  const normalizedBasePath = basePath === "/" ? "" : basePath.replace(/\/+$/, "");
+  for (const file of files) {
+    const segments = file.relativePath.split("/");
+    const url = buildAssetUrl(normalizedBasePath, segments);
+    let parent = root;
+    for (let index = 0; index < segments.length; index += 1) {
+      const originalName = segments[index];
+      const isFile = index === segments.length - 1;
+      const key = toAssetKey(originalName, isFile);
+      let child = parent.children.get(key);
+      if (child && child.originalName !== originalName) {
+        throw new Error(
+          `Asset names "${child.originalName}" and "${originalName}" both map to "${key}". Rename one path segment so generated keys stay unique.`
+        );
+      }
+      if (!child) {
+        child = { originalName, children: /* @__PURE__ */ new Map() };
+        parent.children.set(key, child);
+      }
+      if (isFile) {
+        if (child.url !== void 0 || child.children.size > 0) {
+          throw new Error(
+            `Asset path "${file.relativePath}" collides with another generated asset key.`
+          );
+        }
+        child.url = url;
+      } else if (child.url !== void 0) {
+        throw new Error(
+          `Asset directory "${file.relativePath}" collides with another generated asset key.`
+        );
+      }
+      parent = child;
+    }
+  }
+  return root;
+}
+function toAssetKey(pathSegment, isFile) {
+  const name = isFile ? pathSegment.slice(0, pathSegment.length - extname(pathSegment).length) : pathSegment;
+  const normalized = name.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2");
+  const words = normalized.match(/[A-Za-z0-9]+/g);
+  if (!words || words.length === 0) {
+    throw new Error(`Asset path segment "${pathSegment}" cannot be converted to a TypeScript key.`);
+  }
+  const [first, ...rest] = words;
+  const key = first.toLowerCase() + rest.map((word) => `${word[0].toUpperCase()}${word.slice(1).toLowerCase()}`).join("");
+  return /^[0-9]/.test(key) ? `_${key}` : key;
+}
+function buildAssetUrl(basePath, segments) {
+  const encodedPath = segments.map((segment) => encodeURIComponent(segment)).join("/");
+  return basePath ? `${basePath}/${encodedPath}` : `/${encodedPath}`;
+}
+function renderAssetModule(root) {
+  const lines = [
+    "/**",
+    " * Generated by @valfuse-node/assets. Do not edit manually.",
+    " */",
+    `export const assets = ${renderObject(root, 0)} as const;`,
+    "",
+    "type AssetLeaves<T> = T extends string",
+    "  ? T",
+    "  : T extends Readonly<Record<string, unknown>>",
+    "    ? AssetLeaves<T[keyof T]>",
+    "    : never;",
+    "",
+    "export type AssetPath = AssetLeaves<typeof assets>;",
+    "",
+    "export default assets;",
+    ""
+  ];
+  return lines.join("\n");
+}
+function renderObject(node, depth) {
+  const children = [...node.children.entries()].sort(
+    ([left], [right]) => compareNames(left, right)
+  );
+  if (children.length === 0) return "{}";
+  const indent = "  ".repeat(depth);
+  const childIndent = "  ".repeat(depth + 1);
+  const properties = children.map(([key, child]) => {
+    const value = child.url === void 0 ? renderObject(child, depth + 1) : JSON.stringify(child.url);
+    return `${childIndent}[${JSON.stringify(key)}]: ${value},`;
+  });
+  return `({
+${properties.join("\n")}
+${indent}})`;
+}
+async function readExistingFile(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function pathsEqual(left, right) {
+  const resolvedLeft = resolve(left);
+  const resolvedRight = resolve(right);
+  return process.platform === "win32" ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase() : resolvedLeft === resolvedRight;
+}
+function compareNames(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// src/cli/index.ts
+var HELP = `valfuse-assets - generate typed TypeScript asset paths
+
+Usage:
+  valfuse-assets [--config <file>] [--check]
+
+Options:
+  --config <file>  Read generator options from a YAML file
+  --check          Exit with an error when the generated file is stale
+  --help, -h       Show this help
+
+The default config file is valfuse-assets.yaml. Defaults for omitted options:
+  input_dir:   public/assets
+  output_file: src/assets/assets.ts
+  base_path:   /assets
+`;
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  if (options.help) {
+    console.log(HELP);
+    return;
+  }
+  const cwd = process.cwd();
+  const config = await readConfig(cwd, options.configFile);
+  const result = await generateAssets({ cwd, config, check: options.check });
+  console.log(
+    `${options.check ? "Asset registry is up to date" : result.changed ? "Generated asset registry" : "Asset registry is up to date"}: ${relative2(cwd, result.outputFile)} (${result.assetCount} assets)`
+  );
+}
+function parseArguments(args) {
+  const options = { check: false, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--check") {
+      options.check = true;
+      continue;
+    }
+    if (argument === "--help" || argument === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (argument === "--config") {
+      const configFile = args[index + 1];
+      if (!configFile || configFile.startsWith("--")) {
+        throw new Error('Option "--config" requires a file path.');
+      }
+      options.configFile = configFile;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--config=")) {
+      const configFile = argument.slice("--config=".length);
+      if (!configFile) throw new Error('Option "--config" requires a file path.');
+      options.configFile = configFile;
+      continue;
+    }
+    throw new Error(`Unknown option "${argument}". Use --help to see available options.`);
+  }
+  return options;
+}
+async function readConfig(cwd, configFile) {
+  const filePath = resolve2(cwd, configFile ?? "valfuse-assets.yaml");
+  let content;
+  try {
+    content = await readFile2(filePath, "utf8");
+  } catch (error) {
+    if (isNodeError2(error) && error.code === "ENOENT") {
+      throw new Error(
+        `Asset config file not found: ${relative2(cwd, filePath)}. Create it or pass --config <file>.`,
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = YAML.parse(content);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new Error(`Could not parse YAML asset config ${relative2(cwd, filePath)}${detail}.`, {
+      cause: error
+    });
+  }
+  return parseConfigObject(parsed, filePath);
+}
+function parseConfigObject(value, filePath) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Asset config must be a YAML mapping: ${filePath}`);
+  }
+  const config = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key !== "input_dir" && key !== "output_file" && key !== "base_path") {
+      throw new Error(`Unknown asset config option "${key}" in ${filePath}.`);
+    }
+    if (typeof entry !== "string" || entry.trim() === "") {
+      throw new Error(`Asset config option "${key}" must be a non-empty string.`);
+    }
+    if (key === "input_dir") config.inputDir = entry;
+    if (key === "output_file") config.outputFile = entry;
+    if (key === "base_path") config.basePath = entry;
+  }
+  return config;
+}
+function isNodeError2(error) {
+  return error instanceof Error && "code" in error;
+}
+main().catch((error) => {
+  console.error(`valfuse-assets: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/dist/index.cjs

@@ -0,0 +1,228 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  DEFAULT_ASSET_GENERATOR_CONFIG: () => DEFAULT_ASSET_GENERATOR_CONFIG,
+  generateAssets: () => generateAssets
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/generator.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var DEFAULT_ASSET_GENERATOR_CONFIG = Object.freeze({
+  inputDir: "public/assets",
+  outputFile: "src/assets/assets.ts",
+  basePath: "/assets"
+});
+var IGNORED_SYSTEM_FILES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+async function generateAssets(options = {}) {
+  const cwd = (0, import_node_path.resolve)(options.cwd ?? process.cwd());
+  const config = normalizeConfig(options.config);
+  const inputDir = (0, import_node_path.resolve)(cwd, config.inputDir);
+  const outputFile = (0, import_node_path.resolve)(cwd, config.outputFile);
+  let inputStats;
+  try {
+    inputStats = await (0, import_promises.lstat)(inputDir);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      throw new Error(`Asset input directory not found: ${inputDir}`, { cause: error });
+    }
+    throw error;
+  }
+  if (!inputStats.isDirectory()) {
+    throw new Error(`Asset input must be a directory and cannot be a symlink: ${inputDir}`);
+  }
+  const files = await collectAssetFiles(inputDir, outputFile);
+  const tree = createAssetTree(files, config.basePath);
+  const source = renderAssetModule(tree);
+  const existingSource = await readExistingFile(outputFile);
+  const changed = existingSource !== source;
+  if (options.check) {
+    if (changed) {
+      throw new Error(
+        `Generated asset registry is missing or out of date: ${(0, import_node_path.relative)(cwd, outputFile)}. Run "npx valfuse-assets" to regenerate it.`
+      );
+    }
+    return { assetCount: files.length, outputFile, changed: false };
+  }
+  if (changed) {
+    await (0, import_promises.mkdir)((0, import_node_path.dirname)(outputFile), { recursive: true });
+    await (0, import_promises.writeFile)(outputFile, source, "utf8");
+  }
+  return { assetCount: files.length, outputFile, changed };
+}
+function normalizeConfig(input = {}) {
+  const config = { ...DEFAULT_ASSET_GENERATOR_CONFIG, ...input };
+  for (const [key, value] of Object.entries(config)) {
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new Error(`Config "${key}" must be a non-empty string.`);
+    }
+  }
+  if (/[?#\\]/.test(config.basePath)) {
+    throw new Error('Config "basePath" cannot contain a query, fragment, or backslash.');
+  }
+  if (!config.basePath.startsWith("/") && !/^https?:\/\//i.test(config.basePath)) {
+    throw new Error('Config "basePath" must start with "/" or be an absolute HTTP(S) URL.');
+  }
+  if (/^https?:\/\//i.test(config.basePath)) {
+    const url = new URL(config.basePath);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error('Config "basePath" must use HTTP or HTTPS.');
+    }
+  }
+  if ((0, import_node_path.extname)(config.outputFile).toLowerCase() !== ".ts") {
+    throw new Error('Config "outputFile" must have a .ts extension.');
+  }
+  return config;
+}
+async function collectAssetFiles(inputDir, outputFile) {
+  const files = [];
+  async function visit(directory, relativeDirectory) {
+    const entries = await (0, import_promises.readdir)(directory, { withFileTypes: true });
+    entries.sort((left, right) => compareNames(left.name, right.name));
+    for (const entry of entries) {
+      if (IGNORED_SYSTEM_FILES.has(entry.name)) continue;
+      const absolutePath = (0, import_node_path.resolve)(directory, entry.name);
+      const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await visit(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.isFile() || pathsEqual(absolutePath, outputFile)) continue;
+      files.push({ relativePath });
+    }
+  }
+  await visit(inputDir, "");
+  return files;
+}
+function createAssetTree(files, basePath) {
+  const root = { originalName: "", children: /* @__PURE__ */ new Map() };
+  const normalizedBasePath = basePath === "/" ? "" : basePath.replace(/\/+$/, "");
+  for (const file of files) {
+    const segments = file.relativePath.split("/");
+    const url = buildAssetUrl(normalizedBasePath, segments);
+    let parent = root;
+    for (let index = 0; index < segments.length; index += 1) {
+      const originalName = segments[index];
+      const isFile = index === segments.length - 1;
+      const key = toAssetKey(originalName, isFile);
+      let child = parent.children.get(key);
+      if (child && child.originalName !== originalName) {
+        throw new Error(
+          `Asset names "${child.originalName}" and "${originalName}" both map to "${key}". Rename one path segment so generated keys stay unique.`
+        );
+      }
+      if (!child) {
+        child = { originalName, children: /* @__PURE__ */ new Map() };
+        parent.children.set(key, child);
+      }
+      if (isFile) {
+        if (child.url !== void 0 || child.children.size > 0) {
+          throw new Error(
+            `Asset path "${file.relativePath}" collides with another generated asset key.`
+          );
+        }
+        child.url = url;
+      } else if (child.url !== void 0) {
+        throw new Error(
+          `Asset directory "${file.relativePath}" collides with another generated asset key.`
+        );
+      }
+      parent = child;
+    }
+  }
+  return root;
+}
+function toAssetKey(pathSegment, isFile) {
+  const name = isFile ? pathSegment.slice(0, pathSegment.length - (0, import_node_path.extname)(pathSegment).length) : pathSegment;
+  const normalized = name.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2");
+  const words = normalized.match(/[A-Za-z0-9]+/g);
+  if (!words || words.length === 0) {
+    throw new Error(`Asset path segment "${pathSegment}" cannot be converted to a TypeScript key.`);
+  }
+  const [first, ...rest] = words;
+  const key = first.toLowerCase() + rest.map((word) => `${word[0].toUpperCase()}${word.slice(1).toLowerCase()}`).join("");
+  return /^[0-9]/.test(key) ? `_${key}` : key;
+}
+function buildAssetUrl(basePath, segments) {
+  const encodedPath = segments.map((segment) => encodeURIComponent(segment)).join("/");
+  return basePath ? `${basePath}/${encodedPath}` : `/${encodedPath}`;
+}
+function renderAssetModule(root) {
+  const lines = [
+    "/**",
+    " * Generated by @valfuse-node/assets. Do not edit manually.",
+    " */",
+    `export const assets = ${renderObject(root, 0)} as const;`,
+    "",
+    "type AssetLeaves<T> = T extends string",
+    "  ? T",
+    "  : T extends Readonly<Record<string, unknown>>",
+    "    ? AssetLeaves<T[keyof T]>",
+    "    : never;",
+    "",
+    "export type AssetPath = AssetLeaves<typeof assets>;",
+    "",
+    "export default assets;",
+    ""
+  ];
+  return lines.join("\n");
+}
+function renderObject(node, depth) {
+  const children = [...node.children.entries()].sort(
+    ([left], [right]) => compareNames(left, right)
+  );
+  if (children.length === 0) return "{}";
+  const indent = "  ".repeat(depth);
+  const childIndent = "  ".repeat(depth + 1);
+  const properties = children.map(([key, child]) => {
+    const value = child.url === void 0 ? renderObject(child, depth + 1) : JSON.stringify(child.url);
+    return `${childIndent}[${JSON.stringify(key)}]: ${value},`;
+  });
+  return `({
+${properties.join("\n")}
+${indent}})`;
+}
+async function readExistingFile(filePath) {
+  try {
+    return await (0, import_promises.readFile)(filePath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function pathsEqual(left, right) {
+  const resolvedLeft = (0, import_node_path.resolve)(left);
+  const resolvedRight = (0, import_node_path.resolve)(right);
+  return process.platform === "win32" ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase() : resolvedLeft === resolvedRight;
+}
+function compareNames(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_ASSET_GENERATOR_CONFIG,
+  generateAssets
+});

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+interface AssetGeneratorConfig {
+    inputDir: string;
+    outputFile: string;
+    basePath: string;
+}
+type AssetGeneratorConfigInput = Partial<AssetGeneratorConfig>;
+interface GenerateAssetsOptions {
+    cwd?: string;
+    config?: AssetGeneratorConfigInput;
+    check?: boolean;
+}
+interface GenerateAssetsResult {
+    assetCount: number;
+    outputFile: string;
+    changed: boolean;
+}
+
+declare const DEFAULT_ASSET_GENERATOR_CONFIG: Readonly<AssetGeneratorConfig>;
+/** Generate a stable, typed registry of asset URLs from a directory tree. */
+declare function generateAssets(options?: GenerateAssetsOptions): Promise<GenerateAssetsResult>;
+
+export { type AssetGeneratorConfig, type AssetGeneratorConfigInput, DEFAULT_ASSET_GENERATOR_CONFIG, type GenerateAssetsOptions, type GenerateAssetsResult, generateAssets };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+interface AssetGeneratorConfig {
+    inputDir: string;
+    outputFile: string;
+    basePath: string;
+}
+type AssetGeneratorConfigInput = Partial<AssetGeneratorConfig>;
+interface GenerateAssetsOptions {
+    cwd?: string;
+    config?: AssetGeneratorConfigInput;
+    check?: boolean;
+}
+interface GenerateAssetsResult {
+    assetCount: number;
+    outputFile: string;
+    changed: boolean;
+}
+
+declare const DEFAULT_ASSET_GENERATOR_CONFIG: Readonly<AssetGeneratorConfig>;
+/** Generate a stable, typed registry of asset URLs from a directory tree. */
+declare function generateAssets(options?: GenerateAssetsOptions): Promise<GenerateAssetsResult>;
+
+export { type AssetGeneratorConfig, type AssetGeneratorConfigInput, DEFAULT_ASSET_GENERATOR_CONFIG, type GenerateAssetsOptions, type GenerateAssetsResult, generateAssets };

package/dist/index.js

@@ -0,0 +1,200 @@
+// src/generator.ts
+import { lstat, mkdir, readFile, readdir, writeFile } from "fs/promises";
+import { dirname, extname, relative, resolve } from "path";
+var DEFAULT_ASSET_GENERATOR_CONFIG = Object.freeze({
+  inputDir: "public/assets",
+  outputFile: "src/assets/assets.ts",
+  basePath: "/assets"
+});
+var IGNORED_SYSTEM_FILES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+async function generateAssets(options = {}) {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const config = normalizeConfig(options.config);
+  const inputDir = resolve(cwd, config.inputDir);
+  const outputFile = resolve(cwd, config.outputFile);
+  let inputStats;
+  try {
+    inputStats = await lstat(inputDir);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      throw new Error(`Asset input directory not found: ${inputDir}`, { cause: error });
+    }
+    throw error;
+  }
+  if (!inputStats.isDirectory()) {
+    throw new Error(`Asset input must be a directory and cannot be a symlink: ${inputDir}`);
+  }
+  const files = await collectAssetFiles(inputDir, outputFile);
+  const tree = createAssetTree(files, config.basePath);
+  const source = renderAssetModule(tree);
+  const existingSource = await readExistingFile(outputFile);
+  const changed = existingSource !== source;
+  if (options.check) {
+    if (changed) {
+      throw new Error(
+        `Generated asset registry is missing or out of date: ${relative(cwd, outputFile)}. Run "npx valfuse-assets" to regenerate it.`
+      );
+    }
+    return { assetCount: files.length, outputFile, changed: false };
+  }
+  if (changed) {
+    await mkdir(dirname(outputFile), { recursive: true });
+    await writeFile(outputFile, source, "utf8");
+  }
+  return { assetCount: files.length, outputFile, changed };
+}
+function normalizeConfig(input = {}) {
+  const config = { ...DEFAULT_ASSET_GENERATOR_CONFIG, ...input };
+  for (const [key, value] of Object.entries(config)) {
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new Error(`Config "${key}" must be a non-empty string.`);
+    }
+  }
+  if (/[?#\\]/.test(config.basePath)) {
+    throw new Error('Config "basePath" cannot contain a query, fragment, or backslash.');
+  }
+  if (!config.basePath.startsWith("/") && !/^https?:\/\//i.test(config.basePath)) {
+    throw new Error('Config "basePath" must start with "/" or be an absolute HTTP(S) URL.');
+  }
+  if (/^https?:\/\//i.test(config.basePath)) {
+    const url = new URL(config.basePath);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error('Config "basePath" must use HTTP or HTTPS.');
+    }
+  }
+  if (extname(config.outputFile).toLowerCase() !== ".ts") {
+    throw new Error('Config "outputFile" must have a .ts extension.');
+  }
+  return config;
+}
+async function collectAssetFiles(inputDir, outputFile) {
+  const files = [];
+  async function visit(directory, relativeDirectory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => compareNames(left.name, right.name));
+    for (const entry of entries) {
+      if (IGNORED_SYSTEM_FILES.has(entry.name)) continue;
+      const absolutePath = resolve(directory, entry.name);
+      const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await visit(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.isFile() || pathsEqual(absolutePath, outputFile)) continue;
+      files.push({ relativePath });
+    }
+  }
+  await visit(inputDir, "");
+  return files;
+}
+function createAssetTree(files, basePath) {
+  const root = { originalName: "", children: /* @__PURE__ */ new Map() };
+  const normalizedBasePath = basePath === "/" ? "" : basePath.replace(/\/+$/, "");
+  for (const file of files) {
+    const segments = file.relativePath.split("/");
+    const url = buildAssetUrl(normalizedBasePath, segments);
+    let parent = root;
+    for (let index = 0; index < segments.length; index += 1) {
+      const originalName = segments[index];
+      const isFile = index === segments.length - 1;
+      const key = toAssetKey(originalName, isFile);
+      let child = parent.children.get(key);
+      if (child && child.originalName !== originalName) {
+        throw new Error(
+          `Asset names "${child.originalName}" and "${originalName}" both map to "${key}". Rename one path segment so generated keys stay unique.`
+        );
+      }
+      if (!child) {
+        child = { originalName, children: /* @__PURE__ */ new Map() };
+        parent.children.set(key, child);
+      }
+      if (isFile) {
+        if (child.url !== void 0 || child.children.size > 0) {
+          throw new Error(
+            `Asset path "${file.relativePath}" collides with another generated asset key.`
+          );
+        }
+        child.url = url;
+      } else if (child.url !== void 0) {
+        throw new Error(
+          `Asset directory "${file.relativePath}" collides with another generated asset key.`
+        );
+      }
+      parent = child;
+    }
+  }
+  return root;
+}
+function toAssetKey(pathSegment, isFile) {
+  const name = isFile ? pathSegment.slice(0, pathSegment.length - extname(pathSegment).length) : pathSegment;
+  const normalized = name.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2");
+  const words = normalized.match(/[A-Za-z0-9]+/g);
+  if (!words || words.length === 0) {
+    throw new Error(`Asset path segment "${pathSegment}" cannot be converted to a TypeScript key.`);
+  }
+  const [first, ...rest] = words;
+  const key = first.toLowerCase() + rest.map((word) => `${word[0].toUpperCase()}${word.slice(1).toLowerCase()}`).join("");
+  return /^[0-9]/.test(key) ? `_${key}` : key;
+}
+function buildAssetUrl(basePath, segments) {
+  const encodedPath = segments.map((segment) => encodeURIComponent(segment)).join("/");
+  return basePath ? `${basePath}/${encodedPath}` : `/${encodedPath}`;
+}
+function renderAssetModule(root) {
+  const lines = [
+    "/**",
+    " * Generated by @valfuse-node/assets. Do not edit manually.",
+    " */",
+    `export const assets = ${renderObject(root, 0)} as const;`,
+    "",
+    "type AssetLeaves<T> = T extends string",
+    "  ? T",
+    "  : T extends Readonly<Record<string, unknown>>",
+    "    ? AssetLeaves<T[keyof T]>",
+    "    : never;",
+    "",
+    "export type AssetPath = AssetLeaves<typeof assets>;",
+    "",
+    "export default assets;",
+    ""
+  ];
+  return lines.join("\n");
+}
+function renderObject(node, depth) {
+  const children = [...node.children.entries()].sort(
+    ([left], [right]) => compareNames(left, right)
+  );
+  if (children.length === 0) return "{}";
+  const indent = "  ".repeat(depth);
+  const childIndent = "  ".repeat(depth + 1);
+  const properties = children.map(([key, child]) => {
+    const value = child.url === void 0 ? renderObject(child, depth + 1) : JSON.stringify(child.url);
+    return `${childIndent}[${JSON.stringify(key)}]: ${value},`;
+  });
+  return `({
+${properties.join("\n")}
+${indent}})`;
+}
+async function readExistingFile(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function pathsEqual(left, right) {
+  const resolvedLeft = resolve(left);
+  const resolvedRight = resolve(right);
+  return process.platform === "win32" ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase() : resolvedLeft === resolvedRight;
+}
+function compareNames(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+export {
+  DEFAULT_ASSET_GENERATOR_CONFIG,
+  generateAssets
+};

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@valfuse-node/assets",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Generate a typed TypeScript registry for static asset paths",
+  "license": "MIT",
+  "keywords": [
+    "assets",
+    "asset-generator",
+    "codegen",
+    "typescript",
+    "cli",
+    "valfuse"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "type": "module",
+  "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"
+    }
+  },
+  "bin": {
+    "valfuse-assets": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && node -e \"import('node:fs/promises').then(({ chmod }) => chmod('dist/cli/index.js', 0o755))\"",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "clean": "node clean.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "26.3.0",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alpinnz/valfuse-node.git",
+    "directory": "packages/assets"
+  },
+  "homepage": "https://github.com/alpinnz/valfuse-node#readme",
+  "bugs": {
+    "url": "https://github.com/alpinnz/valfuse-node/issues"
+  }
+}