Lambé 0.9.0

.claude/skills/lambe/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: lambe
+description: Query, filter, transform, validate, and convert structured data files (JSON, YAML, TOML, HCL/Terraform, CSV, TSV, Markdown) using the `lam` CLI. Use when the user asks to extract a field, filter records, aggregate values, check structure, validate against a schema, or convert between formats. Works on config files, API responses, deployment manifests, data exports, and Markdown documents (parsed as a typed AST). Bounded — no recursion, no `def`, no regex; for those the user should reach for a real programming language.
+license: MIT
+metadata:
+  homepage: https://pub.dev/packages/lambe
+  repository: https://github.com/hakimjonas/lambe
+---
+
+# Lambé (`lam`) — structured data queries
+
+Lambé is on the user's PATH after `dart pub global activate lambe`. You
+invoke it via shell. The binary is named `lam`.
+
+## When to reach for `lam`
+
+The user wants to do something with a **structured data file**:
+- "Get the X field from this JSON"
+- "Filter the Y where Z"
+- "Sum / count / list / sort the items"
+- "What's the structure of this file?"
+- "Check that the deployment has at least 2 replicas"
+- "Convert this YAML to TOML"
+- "List all the headings in this README"
+
+Don't reach for `lam` when:
+- The data is binary, in a database, or a stream.
+- The user explicitly asked for jq syntax (use jq).
+- The query needs recursion, `try`/`catch`, regex, or accumulating state — write code instead.
+
+## Core moves
+
+```bash
+# Extract — single value or path
+lam '.database.host' config.toml
+
+# Filter + project
+lam '.users | filter(.age > 30) | map(.name)' data.json
+
+# Aggregate
+lam '.items | map(.price) | sum' data.json
+
+# Inspect structure (returns JSON Schema)
+lam --print-shape data.json
+
+# Static query trace (no execution; surfaces shape per stage + warnings)
+lam --explain '.config | flatten | as(toml)' data.json
+
+# CI assertion (exit 0 on true, 1 on false)
+lam --assert '.replicas >= 2' deployment.yaml
+
+# Convert format
+lam --to yaml '.config' data.json
+
+# Run without input (literal-only queries)
+lam -n '[1, 2, 2, 3] | unique'
+
+# Markdown headings (use `text` op, not `.children[0].text`)
+lam '.children | filter(.type == "heading") | map(text)' README.md
+```
+
+## Syntax in 30 seconds
+
+**Property access**: `.field`, `.users[0]`, `.users[-1]`, `.tags[1:3]`,
+`.["x-axis"]` (bracket form for non-identifier keys).
+
+**Pipeline ops** chained with `|`:
+`filter(p)`, `map(e)`, `sort`, `sort_by(k)`, `group_by(k)`, `unique`,
+`unique_by(k)`, `flatten`, `reverse`, `length`, `first`, `last`,
+`sum`, `avg`, `min`, `max`, `keys`, `values`, `has("k")`,
+`to_entries`, `from_entries`, `to_number`, `type`,
+`filter_values(p)`, `map_values(e)`, `filter_keys(p)`, `text` (markdown),
+`as(fmt)` (cross-format bridge).
+
+**Expressions**: arithmetic `+ - * / %`, comparison `< > <= >= == !=`,
+boolean `&& || !`, null fallback `//`, conditional `if c then a else b`,
+object construction `{name, total: .price * .qty}`, string interpolation
+`"\(.name) is \(.age)"`, list literal `[1, 2, 3]`.
+
+**Boolean keywords**: lambé's logic operators are `&&` `||` `!`. Don't
+write `and` `or` `not` — the parser will tell you, but save the round trip.
+
+## Markdown data model
+
+Markdown parses to a CommonMark AST. Root is `{type: "document", children: [...]}`.
+Every node has a `type`. Container nodes have `children`; leaves carry
+content directly.
+
+Common queries:
+
+```bash
+# Heading texts (use `text` op for prose extraction)
+lam '.children | filter(.type == "heading") | map(text)' doc.md
+
+# Headings with levels
+lam '.children | filter(.type == "heading") | map({level, title: text})' doc.md
+
+# Code blocks by language
+lam '.children | filter(.type == "code_block") | map({language, code})' doc.md
+
+# Whole document as plain text
+lam '. | text' doc.md
+```
+
+The `text` op walks any node tree and concatenates prose recursively
+(text + code + code_block + image alt). Use it instead of
+`.children[0].text` — that pattern only sees the first immediate child
+and misses nested emphasis, links, and inline code.
+
+## Common gotchas
+
+- **Output is pretty-printed JSON by default.** Pass `--no-pretty` for
+  compact output, or `-r` for raw top-level strings (no quotes).
+- **Lambé's null contract**: navigation returns null (`.missing` is null,
+  doesn't throw); computation throws (`.missing + 5` errors). Use
+  `.field == null` to test, or `.field // default` to substitute.
+- **Empty-list policy**: `first`/`last` return null on empty;
+  `min`/`max`/`avg` throw; `sum` returns 0.
+- **Heterogeneous lists** widen to `any` in shape inference. Real-world
+  markdown children, mixed JSON arrays. The shape system is honest about
+  this; `--print-shape` shows the widening.
+- **Output format errors give actionable hints.** If `lam --to toml ...`
+  rejects the shape, the error names the `as(...)` bridge to apply.
+- **`--explain` is your friend** when a query is unexpectedly empty or
+  errors. It prints the shape at every stage statically, plus warnings
+  for runtime-rejected ops and provably-empty filters.
+
+## What lambé deliberately doesn't do
+
+`..` recursive descent, `def` user functions, `try`/`catch`, regex,
+`getpath`/`setpath`, in-place mutation, streaming. If you draft a
+query needing any of these, lambé will tell you with an "unknown
+pipe op" error or a `_jqIdiomHint`. The repo's `doc/non-goals.md`
+documents the lambé idiom that replaces each omission.
+
+## When you hit something this skill doesn't cover
+
+The repo's `AGENTS.md` has the broader reference (more examples, full
+pipeline op list, error pattern table, format auto-detect rules).
+`doc/syntax.md` is the language reference. `doc/recipes.md` has
+end-to-end examples. The MCP server `lam-mcp` is available for
+sandboxed agents that can't shell out.

.github/workflows/ci.yml

@@ -12,6 +12,8 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: dart-lang/setup-dart@v1.7.2
+        with:
+          sdk: 3.12.0
       - run: dart pub get
       - run: cd lambe_test && dart pub get && cd ..
       - run: dart analyze --fatal-infos
@@ -21,6 +23,8 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: dart-lang/setup-dart@v1.7.2
+        with:
+          sdk: 3.12.0
       - run: dart pub get
       - run: dart format --set-exit-if-changed .
 
@@ -29,6 +33,19 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: dart-lang/setup-dart@v1.7.2
+        with:
+          sdk: 3.12.0
       - run: dart pub get
       - run: dart test
       - run: cd lambe_test && dart pub get && dart test
+
+  lint-changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dart-lang/setup-dart@v1.7.2
+        with:
+          sdk: 3.12.0
+      - run: dart pub get
+      - run: dart compile exe bin/lam.dart -o lam
+      - run: ./tool/lint_changelog.sh

.github/workflows/release.yml

@@ -29,6 +29,8 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: dart-lang/setup-dart@v1.7.2
+        with:
+          sdk: 3.12.0
 
       - run: dart pub get
       - run: dart run tool/gen_version.dart
@@ -56,6 +58,14 @@ jobs:
           path: artifacts
           merge-multiple: true
 
+      - name: Generate checksums.txt
+        run: |
+          cd artifacts
+          # One SHA256 per line, matching sha256sum / shasum -a 256 format.
+          # install.sh reads this to verify downloaded binaries.
+          sha256sum lam-* > checksums.txt
+          cat checksums.txt
+
       - uses: softprops/action-gh-release@v3
         with:
           files: artifacts/*
@@ -88,7 +98,7 @@ jobs:
             "\$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
             "name": "io.github.hakimjonas/lambe",
             "title": "Lambe",
-            "description": "Query JSON, YAML, TOML, HCL, CSV, TSV, and Markdown with a composable pipeline syntax.",
+            "description": "A query language for structured data that shows you what you're working with. Shape-aware --explain, JSON Schema input, format bridges.",
             "repository": {
               "url": "https://github.com/hakimjonas/lambe.git",
               "source": "github"

.gitignore

@@ -8,10 +8,21 @@ doc/api/
 *.iml
 .vscode/
 
+# Claude Code local state (settings, session caches). The
+# .claude/skills/ subdirectory is the exception — it ships an Agent
+# Skills package to GitHub for AI coding agents working on lambé and
+# is tracked deliberately. .pubignore separately excludes the whole
+# .claude/ tree from the pub.dev publish payload.
+# `.claude/*` (not `.claude/`) so the negation can re-include
+# subdirectories — git won't descend into a directory ignored by name.
+.claude/*
+!.claude/skills/
+
 .DS_Store
 Thumbs.db
 
 # Compiled binaries
+lam
 lam-mcp
 
 # Local dependency overrides
@@ -26,3 +37,6 @@ bench-results-*.json
 
 # Session handover notes (internal workflow, not code)
 HANDOVER_*.md
+
+# Local scratch notes (release planning, status snapshots, etc.)
+*.scratch.md

.pubignore

@@ -2,8 +2,43 @@ HANDOVER_*.md
 bench-results-*.json
 tool/bench/
 doc/api/
-# Stale local AOT build; per-platform binaries are published via CI
+
+# Stale local AOT builds; per-platform binaries are published via CI
 # to the GitHub release and consumed by the MCP registry. Pub clients
-# rebuild from source on `dart pub global activate`, so shipping this
-# is dead weight.
+# rebuild from source on `dart pub global activate`, so shipping these
+# is dead weight (and locks pub.dev consumers to a Linux x86_64 binary
+# that's useless on other platforms).
+lam
 lam-mcp
+
+# Local scratch notes (release planning, status snapshots, etc.).
+# Same intent as the matching `.gitignore` rule, repeated here because
+# `.pubignore` does not inherit from `.gitignore`.
+*.scratch.md
+
+# Claude Code session state and skill bundles. The .claude/skills/
+# subdirectory ships an Agent Skills package for AI coding agents
+# working in a clone of this repo; pub.dev consumers (Dart developers)
+# don't load skills, so it would just be noise on the package page.
+.claude/
+
+# Cross-vendor Agent Skills path (recognised by Gemini CLI and others
+# as the interoperable alias for .claude/skills/). Same exclusion logic.
+.agents/
+
+# Agent-facing instruction docs. Read by Cursor, Copilot, Claude Code,
+# Gemini CLI, Devin, and other agents inspecting a cloned repo.
+# pub.dev consumers (Dart developers) don't need them.
+AGENTS.md
+
+# Local pubspec overrides.
+pubspec_overrides.yaml
+
+# MCP registry tokens.
+.mcpregistry_*
+
+# MCP registry manifest template — regenerated by .github/workflows/release.yml
+# at release time and consumed by the MCP registry publish flow. Pub.dev
+# consumers never use it, and the placeholder version in the file would be
+# misleading if shipped.
+server.json