lukedj78/dev-flow / forms
forms
VerifiedBuild or edit any form in a Next.js 16 App Router app through one shared toolkit in `lib/forms/`, with dirty + valid Save gating — on TanStack Form + Zod (default) or react-hook-form (auto-detected). Use when the user says "form", "edit panel", "create dialog", "settings page", "save button", "dirty state", or reaches for `useState` to hold field values, raw `useForm`, hand-rolled dirty tracking, or inline `toast.success/error` on submit. Also owns multi-step question flows — "questionnaire", "questionario", "survey", "sondaggio", "quiz", "poll", "onboarding flow", "intake form", "wizard", "step-by-step questions", "one question at a time" — which route to the shadcn `<Questionnaire />`. Refuses outside Next.js 16 web. Not for: React Native forms, search boxes that only filter, reads that populate a form (`data-fetching`), or state not bound to form fields (`state-discipline`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 38.2 KB |
| references/audit-recipe.md | markdown | 8.7 KB |
| references/contracts.md | markdown | 105.8 KB |
| references/form-actions.md | markdown | 4.5 KB |
| references/toolkit-rhf.md | markdown | 13.1 KB |
| references/toolkit-tanstack.md | markdown | 15.6 KB |
| scripts/meta_io.py | script | 9.2 KB |
| scripts/scaffold_lib_forms.pyexecutable | script | 14.3 KB |
scripts/meta_io.py
View on GitHub"""Safe writes for `.workflow/meta.json`: atomic replace, plus a lock around read-modify-write.
Every script in this folder that changes meta.json goes through here. It used to be a plain
`write_text` with no lock, and that failed in two ways (AUDIT.md §6.2):
- Two writers in parallel each read the old file, and the second save erased the first one's
change. Twenty `append-history` runs kept 11 to 15 entries, and every process exited 0.
- `write_text` truncates first and writes second, so a reader in between saw an empty file. If a
crash landed there, it left the empty file behind, and every script then failed on it.
Usage:
with meta_io.locked(root / ".workflow"):
meta = meta_io.load_or_exit(meta_path) # refuses an invalid file with exit 2, changes nothing
... # change meta
meta_io.write_json(meta_path, meta)
The lock is `flock` on the `.workflow` directory itself, not on meta.json. `os.replace` swaps
meta.json's inode, so a process waiting on the old file would wake up holding a lock on a file
nobody reads. Locking the directory also leaves no lock file in a folder that projects commit.
The lock is advisory: a writer that does not take it can still clobber. Where `fcntl` is
missing (Windows), the lock does nothing, and the write is still atomic.
Standard library only, like every script the skills ship.
"""
from __future__ import annotations
import hashlib
import json
import os
import sys
import tempfile
from contextlib import contextmanager
from pathlib import Path
from typing import Any, Iterator
try:
import fcntl
except ImportError: # Windows
fcntl = None # type: ignore[assignment]
# The contract version a meta.json conforms to, recorded in it as `contract_version` on every write. Bump it
# only with a breaking contract change, together with the migration that brings older files up to it. A file
# without the field predates it and is version 1-compatible. A script never rewrites a file whose version is
# higher than the one it knows: it would save back fields whose meaning it does not have.
CONTRACT_VERSION = 1
# Every write through here stamps `meta_digest`: {"sha256": the content's hash, "checked_phase": the last
# phase the phase gates checked}. A hand edit leaves the hash stale, so it can be told from a scripted write.
# And a phase moved by hand differs from checked_phase, so update_meta.py checks the gates from checked_phase,
# not from the phase that was typed in (AUDIT.md P1-33). Only update_meta.py, after the gates pass, moves
# checked_phase forward; every other writer carries it over unchanged, so no later write can launder a phase
# that was moved by hand. The hash is over the parsed values, so reformatting the file is not an edit.
DIGEST_KEY = "meta_digest"
def digest_of(meta: dict[str, Any]) -> str:
"""sha256 (16 hex) of the document's values, without the digest itself; key order and layout ignored."""
body = {k: v for k, v in meta.items() if k != DIGEST_KEY}
canonical = json.dumps(body, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]
def edited_outside(meta: dict[str, Any]) -> bool:
"""True when a digest is present and no longer matches: the file changed since a script last wrote it."""
stamp = meta.get(DIGEST_KEY)
return isinstance(stamp, dict) and stamp.get("sha256") != digest_of(meta)
def checked_phase(meta: dict[str, Any]) -> Any:
"""The last phase the gates checked. A file from before the digest is trusted as it is."""
stamp = meta.get(DIGEST_KEY)
if isinstance(stamp, dict) and isinstance(stamp.get("checked_phase"), str):
return stamp["checked_phase"]
return meta.get("phase")
class InvalidMeta(ValueError):
"""meta.json is not something a script can safely read or rewrite."""
# The containers scripts read with .get(), .append() and .items(). When one held the wrong type, some
# scripts crashed on it and others saved it back unchanged (AUDIT.md §6.2). `phase` is not checked here:
# a wrong phase is refused by update_meta.py and repaired with `set-phase --allow-regress`, and that
# repair needs the file to load. A missing container is fine; `null` is not, because `setdefault` keeps it.
CONTAINERS = {"history": list, "artifacts": dict, "stack": dict, "stack_config": dict}
_JSON_TYPES = {dict: "an object", list: "an array", str: "a string", int: "a number", float: "a number",
bool: "a boolean", type(None): "null"}
def read_meta(path: Path) -> dict[str, Any]:
"""Parse meta.json and check its structure; raise InvalidMeta saying what is wrong."""
try:
text = path.read_text(encoding="utf-8")
except UnicodeDecodeError as e:
raise InvalidMeta(f"it is not UTF-8 text ({e.reason})") from None
if not text.strip():
raise InvalidMeta("the file is empty")
try:
meta = json.loads(text)
except json.JSONDecodeError as e:
raise InvalidMeta(f"it is not valid JSON ({e.msg}, line {e.lineno} column {e.colno})") from None
if not isinstance(meta, dict):
raise InvalidMeta(f"its top level is {_JSON_TYPES.get(type(meta), type(meta).__name__)}, not an object")
for key, kind in CONTAINERS.items():
if key in meta and not isinstance(meta[key], kind):
raise InvalidMeta(f"`{key}` is {_JSON_TYPES.get(type(meta[key]), type(meta[key]).__name__)}, "
f"not {_JSON_TYPES[kind]}")
if DIGEST_KEY in meta and not isinstance(meta[DIGEST_KEY], dict):
raise InvalidMeta(f"`{DIGEST_KEY}` is {_JSON_TYPES.get(type(meta[DIGEST_KEY]), type(meta[DIGEST_KEY]).__name__)}, not an object")
version = meta.get("contract_version")
if "contract_version" in meta and (not isinstance(version, int) or isinstance(version, bool) or version < 1):
raise InvalidMeta(f"`contract_version` is {version!r}, not a positive integer")
for key, entry in (meta.get("artifacts") or {}).items():
if not isinstance(entry, dict):
raise InvalidMeta(f"artifact `{key}` is {_JSON_TYPES.get(type(entry), type(entry).__name__)}, "
"not an object")
return meta
def load_or_exit(path: Path) -> dict[str, Any]:
"""read_meta for a command-line script: on an invalid file, say why and exit 2, having changed nothing."""
try:
return read_meta(path)
except InvalidMeta as e:
sys.stderr.write(
f"{path} is not a valid meta.json: {e}.\n"
" Nothing was changed. Fix it by hand, or restore the last committed version with\n"
f" git checkout -- {path}\n"
)
sys.exit(2)
@contextmanager
def locked(workflow_dir: Path) -> Iterator[None]:
"""Hold an exclusive lock on `workflow_dir` for the duration of the block.
If the folder does not exist, this does nothing. The caller reports the missing meta.json
itself, and a lock must not create the folder as a side effect.
"""
if fcntl is None or not workflow_dir.is_dir():
yield
return
fd = os.open(workflow_dir, os.O_RDONLY)
try:
fcntl.flock(fd, fcntl.LOCK_EX)
yield
finally:
os.close(fd) # closing the descriptor releases the lock
def write_text(path: Path, text: str) -> None:
"""Replace `path` with `text` atomically: readers see the old file or the new one, never a mix."""
fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
try:
with os.fdopen(fd, "w", encoding="utf-8") as f:
f.write(text)
f.flush()
os.fsync(f.fileno())
if path.exists():
os.chmod(tmp, path.stat().st_mode & 0o777)
else:
# mkstemp creates the file 0600; a new meta.json gets the usual 0644 minus the umask.
umask = os.umask(0)
os.umask(umask)
os.chmod(tmp, 0o666 & ~umask)
os.replace(tmp, path)
except BaseException:
try:
os.unlink(tmp)
except FileNotFoundError:
pass
raise
def write_json(path: Path, data: Any, phase_checked: str | None = None) -> None:
"""Write `data` in meta.json's usual layout (2-space indent, UTF-8, trailing newline), atomically,
stamped with CONTRACT_VERSION and `meta_digest`. A file written under a newer contract is refused with
exit 2, untouched. `phase_checked` is passed only by a phase move whose gates just passed; without it the
previously checked phase is carried over."""
if isinstance(data, dict):
version = data.get("contract_version")
if isinstance(version, int) and not isinstance(version, bool) and version > CONTRACT_VERSION:
sys.stderr.write(
f"{path} was written under a newer dev-flow contract (version {version}; this script knows "
f"{CONTRACT_VERSION}).\n Nothing was changed. Update the dev-flow skills, then run this again.\n")
sys.exit(2)
data["contract_version"] = CONTRACT_VERSION
carried = phase_checked if phase_checked is not None else checked_phase(data)
data[DIGEST_KEY] = {"sha256": digest_of(data), "checked_phase": carried}
write_text(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |