api #

a web app template with TypeScript + SvelteKit + optional Rust for the fuz-stack

3 modules · 48 declarations

Modules
#

Action
#

molt.ts view source

Action

type { kind: "replace_once"; path: string; anchor: string; replacement: string; label: string; } | { kind: "remove_line"; path: string; prefix: string; suffix: string; label: string; } | { kind: "replace_all"; path: string; from: string; to: string; label: string; } | { kind: "replace_file"; path: string; anchors: string[]; content: string; label: string; } | { kind: "create_file"; path: string; content: string; label: string; } | { kind: "rename_dir"; from: string; to: string; } | { kind: "delete_file"; path: string; } | { kind: "delete_dir"; path: string; }

import type {Action} from '@fuzdev/fuz_template/molt.js';

A single filesystem transformation in a molt plan. Paths are relative to the repo root.

apply
#

molt.ts view source

(root: string, plan: Action[]): void import {apply} from '@fuzdev/fuz_template/molt.js';

Applies a verified plan at root. Callers must run verify and conflicts first — apply assumes anchors match, targets exist, and nothing is in the way of created files.

root

type string

plan

type Action[]

returns

void

apply_gate
#

molt.ts view source

(wetrun: boolean, clean: boolean, is_interactive: boolean): ApplyGate import {apply_gate} from '@fuzdev/fuz_template/molt.js';

wetrun

type boolean

clean

type boolean

is_interactive

type boolean

returns

ApplyGate

ApplyGate
#

molt.ts view source

ApplyGate

type "apply" | "confirm" | "confirm_dirty" | "dry_run" | "refuse_dirty"

import type {ApplyGate} from '@fuzdev/fuz_template/molt.js';

What stands between a printed plan and applying it, given the run mode.

A terminal always gets a confirm prompt — the wizard's answers were just typed, and one keystroke catches a typo'd name before it hits disk. The one combination with no gate at all is --wetrun on a clean tree without a terminal — there git reset --hard && git clean -fd restores the pre-molt state (the tree was clean, so git clean removes only files molt created). A dirty tree (reachable only via --force) never applies without the dirty-specific in-the-moment confirmation, and without a terminal it never applies at all: "commit first" is always available, so an override flag would just recreate the hole.

build_plan
#

molt.ts view source

(config: MoltConfig, templates: Templates): Action[] import {build_plan} from '@fuzdev/fuz_template/molt.js';

Builds the full molt plan from resolved choices. Pure — reads nothing.

config

templates

returns

Action[]

cascade
#

molt.ts view source

(kept: Set<string>): void import {cascade} from '@fuzdev/fuz_template/molt.js';

Strips any feature whose requires parent is stripped.

kept

type Set<string>

returns

void

mutates

  • kept

check_all
#

molt.ts view source

(root: string): CheckIssues import {check_all} from '@fuzdev/fuz_template/molt.js';

Verifies the plans for both sample configs, covering every anchor molt can touch (each feature exercised kept in one config and stripped in the other), plus the embedded-template invariants that anchors alone can't see.

root

type string

returns

CheckIssues

CheckIssues
#

molt.ts view source

CheckIssues import type {CheckIssues} from '@fuzdev/fuz_template/molt.js';

What check_all found, split by remedy.

drift

Anchors or embedded templates the template drifted from.

type string[]

conflicts

Template files in the way of files molt creates.

type string[]

CLI
#

CliError
#

molt.ts view source

import {CliError} from '@fuzdev/fuz_template/molt.js';

Errors surfaced by molt.

Exit-code dialect: 0 success; 2 = the caller must change something local (arguments, git state, modified files) before retrying; 1 = everything else.

inheritance

extends: Error

kind

type CliErrorKind

remediation

type string | null

constructor

type new (kind: CliErrorKind, message: string, remediation?: string | null): CliError

kind

message

type string

remediation

type string | null
default null

usage

type (message: string): CliError

static

message

type string
returns CliError

precondition

type (message: string, hint?: string | null): CliError

static

message

type string

hint

type string | null
default null
returns CliError

drift

type (issues: string[]): CliError

static

issues

type string[]
returns CliError

exit_code

Maps the error to its stable exit code.

type (): number

returns number

hint

An optional remediation hint printed under the error.

type (): string | null

returns string | null

CliErrorKind
#

molt.ts view source

CliErrorKind

type "usage" | "precondition" | "drift" | "io" | "terminal"

import type {CliErrorKind} from '@fuzdev/fuz_template/molt.js';

conflicts
#

molt.ts view source

(root: string, plan: Action[]): string[] import {conflicts} from '@fuzdev/fuz_template/molt.js';

Lists the files the plan creates that already exist at root, kept apart from verify's drift because the remedy differs.

root

type string

plan

type Action[]

returns

string[]

describe
#

molt.ts view source

(action: Action): string import {describe} from '@fuzdev/fuz_template/molt.js';

action

type Action

returns

string

DOCS
#

DOCS_NEEDS_REPO
#

molt.ts view source

"keeping docs needs a repository url (the API docs link to source) — pass --repo <url>, or --strip docs" import {DOCS_NEEDS_REPO} from '@fuzdev/fuz_template/molt.js';

The non-interactive refusal to keep docs without a repository url.

empty_groups
#

molt.ts view source

(kept: Set<string>): string[] import {empty_groups} from '@fuzdev/fuz_template/molt.js';

Kept features whose required members are all stripped — invalid combinations the caller must reject (or repair by stripping the parent too). Registry order, so callers report deterministically.

kept

type Set<string>

returns

string[]

Feature
#

molt.ts view source

Feature import type {Feature} from '@fuzdev/fuz_template/molt.js';

A molt-selectable feature of the template.

id

Stable id used by --keep/--strip (kebab-case).

type string

prompt

Wizard prompt, phrased as "keep X?".

type string

default_keep

Whether the feature is kept when unspecified.

type boolean

requires

A feature this one is part of — stripping the parent strips this too.

type string | null

member_of

A feature this one provides a required member for — the parent can't be kept unless at least one of its members is kept (e.g. cargo refuses to load a workspace with no member crates).

type string | null

FEATURES
#

git_output
#

molt.ts view source

(root: string, args: string[]): string | null import {git_output} from '@fuzdev/fuz_template/molt.js';

Runs a git command at root, returning its stdout on success and null on a nonzero exit (e.g. no origin remote configured). Clears the INHERITED_GIT_ENV variables so git always resolves the repo from root.

root

type string

args

type string[]

returns

string | null

throws

  • `CliError` when git can't be spawned at all.

GITHUB_EXTRAS
#

molt.ts view source

"github-extras" import {GITHUB_EXTRAS} from '@fuzdev/fuz_template/molt.js';

json_escape
#

molt.ts view source

(value: string): string import {json_escape} from '@fuzdev/fuz_template/molt.js';

Escapes a string for embedding in a JSON string literal (also valid for TOML basic strings, which share the \"/\\/\n escapes).

value

type string

returns

string

lines_with_prefix
#

molt.ts view source

(content: string, prefix: string): { start: number; end: number; }[] import {lines_with_prefix} from '@fuzdev/fuz_template/molt.js';

The ranges of the lines in content that start with prefix, each including its trailing newline when it has one.

content

type string

prefix

type string

returns

{ start: number; end: number; }[]

load_templates
#

molt.ts view source

(root: string): Templates import {load_templates} from '@fuzdev/fuz_template/molt.js';

root

type string

returns

Templates

members_of
#

molt.ts view source

(parent: string): Feature[] import {members_of} from '@fuzdev/fuz_template/molt.js';

The features that provide required members for parent.

parent

type string

returns

Feature[]

MoltConfig
#

molt.ts view source

MoltConfig import type {MoltConfig} from '@fuzdev/fuz_template/molt.js';

Fully-resolved molt choices, assembled from flags and wizard answers. kept holds the feature ids (from FEATURES) to keep.

name

type string

npm_name

type string

description

type string

domain

type string | null

repo_url

type string | null

kept

type Set<string>

Mreow
#

mreow_items
#

Mreows
#

normalize_remote_url
#

molt.ts view source

(url: string): string | null import {normalize_remote_url} from '@fuzdev/fuz_template/molt.js';

Normalizes the git origin url with to_repo_url, returning null for the template's own remote (a plain git clone of fuz_template keeps origin pointed at the template — deriving that would be wrong). GitHub owner and repo names are case-insensitive, so the check is too.

url

type string

returns

string | null

parse_ids
#

molt.ts view source

(values: string[]): string[] import {parse_ids} from '@fuzdev/fuz_template/molt.js';

Splits repeatable/CSV flag values into feature ids, validating each.

values

type string[]

returns

string[]

throws

  • `CliError` on an unknown id.

parse_optional_repo_url
#

molt.ts view source

(value: string): string | null import {parse_optional_repo_url} from '@fuzdev/fuz_template/molt.js';

Like parse_repo_url, but blank input (after trim_url) is no url.

value

type string

returns

string | null

parse_repo_url
#

molt.ts view source

(value: string): string import {parse_repo_url} from '@fuzdev/fuz_template/molt.js';

Parses a repository url given as a flag or wizard answer into its web url via to_repo_url, so an ssh remote pasted as-is still yields working source links in the API docs.

value

type string

returns

string

parse_top_level
#

molt.ts view source

(args: string[]): TopLevel | null import {parse_top_level} from '@fuzdev/fuz_template/molt.js';

Parses argv into the flag struct, or null when --help was printed.

args

type string[]

returns

TopLevel | null

throws

  • `CliError` on unknown flags or a bad subcommand.

Positioned
#

Positioned.svelte view source

accepts children

import Positioned from '@fuzdev/fuz_template/Positioned.svelte';

x

type number

y

type number

scale

type number

children

type Snippet<[]>

render
#

molt.ts view source

(template: string, substitutions: [string, string][]): string import {render} from '@fuzdev/fuz_template/molt.js';

Substitutes __PLACEHOLDER__ tokens in a template.

Single-pass over the template: inserted values are never re-scanned, so user-provided text (a description containing __RUST_SECTION__, say) can't corrupt the output.

template

type string

substitutions

type [string, string][]

returns

string

resolve
#

molt.ts view source

(keep: string[], strip: string[]): { kept: Set<string>; explicit: Set<string>; } import {resolve} from '@fuzdev/fuz_template/molt.js';

Resolves the kept-feature set from --keep/--strip flags, applying defaults and the requires cascade. explicit returns which features the flags decided (the wizard prompts only for the rest).

keep

type string[]

strip

type string[]

returns

{ kept: Set<string>; explicit: Set<string>; }

throws

  • `CliError` on conflicting flags.

resolve_config
#

molt.ts view source

(top: TopLevel, root: string, is_interactive: boolean): Promise<MoltConfig> import {resolve_config} from '@fuzdev/fuz_template/molt.js';

top

root

type string

is_interactive

type boolean

returns

Promise<MoltConfig>

RUST
#

sample_configs
#

molt.ts view source

(): [MoltConfig, MoltConfig] import {sample_configs} from '@fuzdev/fuz_template/molt.js';

Two configs that together exercise every plan branch: one keeps every registry feature (derived from FEATURES, so a new feature is covered without touching this) and sets every optional value, one strips every feature and clears the optional values.

returns

[MoltConfig, MoltConfig]

Templates
#

molt.ts view source

Templates import type {Templates} from '@fuzdev/fuz_template/molt.js';

The output templates from crates/molt/templates/, substituted with __PLACEHOLDER__ tokens. The Rust twin embeds these at compile time; here they're read from the working tree (always present pre-molt).

PAGE_SVELTE

type string

README_MD

type string

CLAUDE_MD

type string

README_RUST_SECTION

type string

CLAUDE_RUST_SECTION

type string

WORKSPACE_CARGO_TOML

type string

FUNDING_YML

type string

EXAMPLE_TS

type string

to_repo_url
#

molt.ts view source

(url: string): string | null import {to_repo_url} from '@fuzdev/fuz_template/molt.js';

Converts a repository url in any common git form (https or http, scp-style git@host:, or ssh://git@host/) to its web url — the ssh forms become https without their ssh port, userinfo (a user or token) is dropped, the scheme is lowercased, an empty port is dropped, a ?query or #fragment is dropped from the ssh:// and http(s) forms (the scp form keeps ?/# as literal path characters), and a trailing / or .git is dropped — returning null for anything else (a local path, a bare owner/repo, an empty host).

url

type string

returns

string | null

TopLevel
#

molt.ts view source

TopLevel import type {TopLevel} from '@fuzdev/fuz_template/molt.js';

name

type string | null

npm_name

type string | null

description

type string | null

domain

type string | null

repo

type string | null

keep

type string[]

strip

type string[]

wetrun

type boolean

force

type boolean

subcommand

type "check" | null

trim_url
#

molt.ts view source

(url: string): string import {trim_url} from '@fuzdev/fuz_template/molt.js';

Trims whitespace and byte-order marks from a url, matching the Rust twin's trim_url (JS's \s covers U+FEFF but not U+0085, Rust's is_whitespace the reverse, so each twin adds the other's).

url

type string

returns

string

validate_description
#

molt.ts view source

(description: string): void import {validate_description} from '@fuzdev/fuz_template/molt.js';

Validates a project description: a single line, no control characters (it lands in package.json, TOML, and markdown blockquotes).

description

type string

returns

void

throws

  • `CliError` when invalid.

validate_domain
#

molt.ts view source

(domain: string): void import {validate_domain} from '@fuzdev/fuz_template/molt.js';

Validates a bare domain like example.com (no scheme, no path).

domain

type string

returns

void

throws

  • `CliError` when invalid.

validate_name
#

molt.ts view source

(name: string): void import {validate_name} from '@fuzdev/fuz_template/molt.js';

Validates a project name: snake_case, usable as a crate name.

name

type string

returns

void

throws

  • `CliError` when invalid.

validate_npm_name
#

molt.ts view source

(name: string): void import {validate_npm_name} from '@fuzdev/fuz_template/molt.js';

Validates an npm package name (scoped names like @you/name allowed): lowercase url-safe characters, no ./_ prefix, npm's 214-char limit.

name

type string

returns

void

throws

  • `CliError` when invalid.

verify
#

molt.ts view source

(root: string, plan: Action[]): string[] import {verify} from '@fuzdev/fuz_template/molt.js';

Verifies every action's preconditions against the tree at root, returning human-readable issues (empty = the plan is applicable).

root

type string

plan

type Action[]

returns

string[]