@lemoncode/lemony 0.5.0 → 0.5.1

package/catalog/VERSION

@@ -1 +1 @@
-0.5.0
+0.5.1

package/catalog/commands/sync-design-tokens.md

@@ -18,7 +18,9 @@ Designer; follow the steps there.
   deletes tool-only variables). Preview the plan, push on confirmation, then record the drift
   baseline only after the push succeeds.
 - _empty_ — check the drift state (`lemony status`) and, if an export is pending and the tool
-  is connected, offer `export`; otherwise report the current state.
+  is connected, offer `export`; otherwise report the current state. `status` shows no drift
+  line both when there is no token file and when the file cannot be read or fails
+  validation — tell the two apart with `lemony doctor`'s `design-tool-drift` check.
 
 The design tool is a **projection** of the canonical JSON, never a peer source of truth.
 Detect the tool at runtime: read the `com.lemony.design-tool` binding at the root of

package/catalog/hooks/init.sh

@@ -46,8 +46,17 @@ WARNINGS=()
 # awk/grep/git (preinstalled) cover the rest.
 CONFIG_VERSION=""
 CONFIG_REPO=""
-if [ ! -f "$CONFIG" ]; then
+if [ ! -e "$CONFIG" ]; then
   ERRORS+=("harness.config.yml not found at $REPO_ROOT. Run \`lemony install\`.")
+elif [ ! -f "$CONFIG" ]; then
+  # There, but not a file awk can read: a directory, or a FIFO it would block on
+  # until something wrote to it. `-e`/`-f` follow a symlink, so a dead link stays
+  # "not found" above and a link to one of these lands here.
+  ERRORS+=("harness.config.yml at $REPO_ROOT is not a regular file (a directory, a FIFO, a socket or a device), so it was not read. Replace it with the config file.")
+elif [ ! -r "$CONFIG" ]; then
+  # A file awk cannot open failed the key check below, so the boot blamed missing keys
+  # under a raw awk error.
+  ERRORS+=("harness.config.yml at $REPO_ROOT cannot be read (check its permissions), so it was not read.")
 elif ! awk '
     { sub(/\r$/, "") }
     /^[^[:space:]#]/ {
@@ -190,6 +199,19 @@ if [ "${#ERRORS[@]}" -eq 0 ] && [ -n "$GIT_USER_EMAIL" ]; then
   CURRENT_PATH="$REPO_ROOT/.claude/state/current-$USER_SLUG.md"
   if [ -z "$USER_SLUG" ]; then
     : # path-unsafe slug — pointer write skipped above
+  elif [ -L "$REPO_ROOT/.claude" ] || [ -L "$REPO_ROOT/.claude/state" ]; then
+    # A linked directory takes the pointer, and every refresh after it, out of the
+    # repo — the same write-through the dangling-link branch below refuses.
+    WARNINGS+=(".claude or .claude/state is a symlink, so the session start was not recorded (the pointer would be written wherever it points). Replace it with a directory.")
+  elif [ -e "$CURRENT_PATH" ] && [ ! -f "$CURRENT_PATH" ]; then
+    # There, but not a file: writing to a FIFO blocks until something reads it, and
+    # awk reading one blocks until something writes. The pointer is not critical, so
+    # the boot goes on without it — a warning, not a blocking error.
+    WARNINGS+=(".claude/state/current-$USER_SLUG.md is not a regular file (a directory, a FIFO, a socket or a device), so the session start was not recorded. Remove it; the next session recreates it.")
+  elif [ -L "$CURRENT_PATH" ] && [ ! -e "$CURRENT_PATH" ]; then
+    # A symlink whose target is gone: `-e`/`-f` follow it and see nothing, and the
+    # `cat >` below would create the target wherever the link points.
+    WARNINGS+=(".claude/state/current-$USER_SLUG.md is a symlink whose target is missing, so the session start was not recorded (writing through it would create the file it points at). Remove it; the next session recreates it.")
   elif [ ! -f "$CURRENT_PATH" ]; then
     mkdir -p "$REPO_ROOT/.claude/state"
     cat > "$CURRENT_PATH" <<EOF

package/catalog/hooks/lib/merge-pr.sh

@@ -309,12 +309,13 @@ fi
 # same recipe as playbook-scan.sh): emit `<key>\t<value>` for the uncommented
 # `checks_timeout_secs` / `allow_no_checks` entries — inline comments stripped
 # (on the block header too) and surrounding quotes removed. Any column-0 line
-# ends the block. Absent/unreadable config → baked defaults.
+# ends the block. Absent/unreadable/non-regular config → baked defaults.
 CONFIG_TIMEOUT=""
 CONFIG_ALLOW_NO_CHECKS=""
 read_merge_config() {
   local config="$ROOT/harness.config.yml"
-  [ -r "$config" ] || return 0
+  # `-f` as well as `-r`: a FIFO is readable, and awk on it would hang the merge.
+  { [ -f "$config" ] && [ -r "$config" ]; } || return 0
 
   local key value
   while IFS=$'\t' read -r key value; do

package/catalog/hooks/lib/playbook-scan.sh

@@ -39,7 +39,8 @@
 # which would breach the per-fire budget) and with no materialized state file to
 # go stale before an `update` command exists (P7). Falls back to the baked
 # defaults when the config, its `paths` block, or a key is absent or commented
-# out (fresh clone, the vendor repo dogfooding itself, an un-customized install).
+# out (fresh clone, the vendor repo dogfooding itself, an un-customized install),
+# and when the config is not a regular file.
 _resolve_playbook_dirs() {
   local repo_root="$1"
   local home_dir="$2"
@@ -47,7 +48,8 @@ _resolve_playbook_dirs() {
   PLAYBOOKS_GLOBAL_DIR="$home_dir/.claude/playbooks"
 
   local config="$repo_root/harness.config.yml"
-  [ -r "$config" ] || return 0
+  # `-f` as well as `-r`: a FIFO is readable, and awk on it would hang the hook.
+  { [ -f "$config" ] && [ -r "$config" ]; } || return 0
 
   # One awk pass: within the top-level `paths:` block, emit `<key>\t<value>` for
   # the (uncommented) `playbooks` / `playbooks_global` entries — inline comments

package/catalog/skills/design-tool-sync/SKILL.md

@@ -70,34 +70,67 @@ variables and the DTCG JSON:
 - `name` — the variable's dotted path. Map it to/from the tool's own grouping separator.
 - `value` for a literal; `ref` for an alias (the name of the variable it points at).
 - `modes` — per-theme overrides (the base theme is `value`/`ref`, not repeated).
+- Every `value` and mode value is a **string** — `"1024"`, not `1024` — and every `ref` a
+  non-empty one; each variable carries a `value` or a `ref` (a `value` beside a `ref` is
+  ignored), and `modes` is an object whose mode names are not blank nor `__proto__`. A name
+  is dot-separated segments, none empty, none starting with `$`, none `__proto__`, not just
+  a tier (`primitive`, `semantic`, `component`), and no two variables share one. The CLI
+  refuses a file that breaks any of these, naming the variable (and the mode, for a mode
+  value).
 
 The CLI maps this to the 3-tier DTCG model: `ref` → an alias `{path}`, `modes` →
-`$extensions["com.lemony.modes"]`, and the tier follows the path (a literal defaults to
-`primitive`, an alias to `semantic` when the name carries no tier).
+`$extensions["com.lemony.modes"]`, and the tier follows the path. A name without a tier
+lands on the one tier `docs/design-tokens.json` already has it in; otherwise a literal
+defaults to `primitive` and an alias to `semantic`. A bare `ref` — or a bare `{alias}` mode
+value — resolves to the tiered path its target lands at in the same neutral file, or to the
+one tier the token file has it in.
 
 ## import — tool → JSON
 
 1. **Read** the tool's variables over MCP and write them to a neutral file (a temp path).
 2. **Preview** the diff (writes nothing):
    `lemony design-tokens import --from=<neutral-file>`. It prints, per token, the target tier
-   and `new` / `changed` (with the old → new value) / `unchanged`.
+   and `new` / `changed` (each thing that changes, old → new: the value, the `$type`, each
+   mode) / `unchanged`. When
+   `docs/design-tokens.json` already fails validation it adds a `Warning:` saying so: the
+   apply will refuse any slice that leaves it failing, so tell the human before curating.
 3. **Present and curate.** Walk the human through it: which new tokens to take, which changes
    to accept, and — where a tool-origin name is ambiguous — whether a literal belongs in
    `primitive` or `semantic`. The human owns the slice.
 4. **Apply** the agreed slice:
    `lemony design-tokens import --from=<neutral-file> --apply --only=<dotted,paths>`.
    This does the additive merge into `docs/design-tokens.json` deterministically (it
-   bootstraps the file if it does not exist yet). Then run `lemony design-tokens validate` to
-   confirm the result is well-formed.
+   bootstraps the file if it does not exist yet and the slice writes something). A changed
+   token keeps what the neutral file does not carry — `$description`, a contrast pairing,
+   other extensions — and an unchanged one is left as it is. A token the tool cannot hold
+   (see export) is never written over: the preview shows it as a change from
+   `(outside the sync: <why>)`, and the apply lists it as not applied. It writes nothing
+   when the merged file would fail validation — typically a `semantic` alias whose
+   `primitive` target is neither in the file nor in the slice: add the target to the same
+   `--only`, or fix the file first. When the neutral file does not carry the target at
+   all, the refusal says so: create it in the tool first, or leave out what references
+   it. An `--only` path no variable lands at is refused rather than skipped. A refusal
+   prints the preview again, so the slice can be re-curated from the paths it lists. Then run
+   `lemony design-tokens validate` to confirm the result is well-formed.
 
 ## export — JSON → tool
 
-1. **Plan.** Read the tool's current variables over MCP into a neutral file, then:
+1. **Plan.** `export` refuses (exit 1) a `docs/design-tokens.json` that fails
+   `lemony design-tokens validate` — fix the file first. Read the tool's current variables
+   over MCP into a neutral file, then:
    `lemony design-tokens export --tool-state=<tool-state> --out=<projection-file>`. It prints
    the additive upsert plan (how many to create, how many to update — **never any deletes**)
    and writes the projection the tool should hold to `<projection-file>`. The `--tool-state`
    is optional; without it every variable is planned as a create (the upsert is idempotent by
-   name either way).
+   name either way). A tool variable named without its tier (`color.brand`) is matched to the
+   path `import` lands it at (`primitive.color.brand`), so when you push, write into that
+   existing variable rather than creating a tiered twin. A token a tool variable cannot hold
+   is not projected: a composite (a shadow, a typography, a cubic Bézier — an object or
+   array `$value`), a token whose modes the neutral format cannot carry (a mode value that
+   is not text, a number or a boolean, a blank or `__proto__` mode name, a modes extension
+   that is not an object), and any alias to one of those. The plan names each as "not
+   projected", with why — say so to the human. `--out` takes a file path (not a pipe, nor
+   the token file itself).
 2. **Confirm.** Show the plan; the human approves.
 3. **Push.** Write the projection's variables into the tool over MCP — create new ones, update
    changed ones, leave tool-only variables untouched.

package/catalog/templates/claude-code/harness.config.yml.tpl

@@ -88,10 +88,13 @@ rollback:
 # extensions (.css/.scss/.ts/.tsx/.vue/.svelte/.astro/.js/.mdx/.html/…). Add extra
 # suffixes here for a stack the built-ins don't cover — additive, never a replacement.
 # Default none.
-# `verify`: a command line `design-tokens contrast` runs after its own WCAG checks
+# `verify`: a command line `design-tokens contrast` runs alongside its own WCAG checks
 # (through `sh -c`, in the repo root) — your design system's own verifier for the rules
 # only it can know (palette under colour-vision-deficiency simulation, property grammar,
-# CSS scans). Its output is forwarded; a non-zero exit fails the gate. Default none.
+# CSS scans). Its output is forwarded; a non-zero exit fails the gate. It runs on every
+# path: with no docs/design-tokens.json only the WCAG pair check is skipped, and a file
+# that cannot be read or parsed is reported alongside it — never the verifier you
+# declared. Default none.
 # design_tokens:
 #   scan_extensions:
 #     - .foo