Machine-readable system — overview

DevSnips treats its machine-readable layer as a first-class product surface, not a byproduct. Everything an agent or integrator needs to query the inventory exists as a structured file, and every structured file is generated from one canonical source. This page explains the surfaces, the generation pipeline that produces them, and how to pick the right one.

The surfaces

Principles

1. One source of truth. library/ + per-resource metadata.json is canonical. Every other surface is derived. Never hand-edit derived files.
2. Determinism. Regenerating over an unchanged repository produces identical output (the registry's lastUpdated date is the one intentional exception).
3. Cross-validation over trust. The primary validator checks registry↔disk agreement in both directions; the registry generator refuses to write when its own validation finds a mismatch.
4. Portability. Registry and index paths are tech-first without the library/ prefix, computed portably (never absolute machine paths). The on-disk location of any entry is library/<path>.
5. Stable identity. The registry path is the resource's identity. IDs must remain stable once published.

The index pipeline: rebuild vs build vs validate

Three distinct scripts under scripts/tooling/indexing/ — each has one job. Do not confuse them.

rebuild_index.py — the master generator

Steps (from its main()):

1. Load the previous index to preserve hand-curated family-level description / tags / searchTerms and variant-level fields.
2. Re-scan the disk for leaves under each content-type tree and rebuild each family/variant path, category, and type from the on-disk location.
3. Cross-validate — every indexed variant must exist on disk and every valid on-disk leaf must be indexed.
4. Recompute stats and technologies[].families from the final family set.
5. Write the index only if validation found no problems; otherwise print the problems and leave the file untouched.

Key internals:

• TAILWIND_TREES / VANILLA_TREES / REACT_TREES — the three (bucket, type, is_template) trees per technology: ("Components","component",False), ("Sections","section",False), ("Templates","template",True). To add a content type, change these, not the output file.
• is_leaf() — Tailwind requires code.html and preview.html; React accepts code.tsx or preview.html; Vanilla is any metadata.json folder without a child metadata.json.
• make_variant() — builds each variant record, including the files manifest (see below).
• validate() — the pre-write problem list. Printing NOT writing index due to validation problems is a failure, not a no-op.

The files manifest

make_variant() builds variant.files from what is actually on disk:

• direct files: code.html, code.tsx, metadata.json, preview.html, README.md, AGENTS.md, …
• plus pages/* (one level deep, prefixed pages/) — Tailwind and Vanilla templates;
• plus src/*, components/*, data/*, sections/*, styles/* (one level deep, prefixed) — React templates.

This manifest is what the CLI installs, so an incomplete manifest means an incomplete install. Files nested deeper than one level below those directories are not listed.

build_resource_indexes.py — the per-type indexes

Builds the three specialized indexes from the same in-memory family set the master used, and refuses to write anything when rebuild_index.validate() reports a problem. Run it after the master changes.

Schema (each specialized index): version, type, description, generatedBy, masterIndex ("snippets-index.json"), pathConvention, stats (families, resources, installable, byTechnology), families[] (sorted by path). Each variant entry carries id (the canonical CLI-resolvable id, npx devsnips add <id>), name, type, path, plus optional description / files / tags / features / styles (omitted when empty) and install (the exact CLI command, derived only when the CLI would find installable files). Paths are tech-first, without the library/ prefix.

validate_indexes.py — the post-hoc gate

Re-scans the disk with rebuild_index's scanner (exact leaf-detection parity, including _template_leaves for template roots that have no root code.html) and fails loudly on: stale entries (indexed path missing on disk), missing resources (disk leaf absent from the index), duplicate ids/paths, wrong type vs parent index, wrong family variantsCount, family/variant path-prefix mismatches, sort-order violations, master↔specialized count mismatches, and JSON parse errors. Exit 0 = the indexes match the repository. Run it after every regeneration.

Determinism

Two runs over the same repository state produce byte-identical specialized indexes (families/variants sorted by path, fixed key order, no timestamps). The master keeps its existing lastUpdated date, which is the only intentional non-determinism.

Choosing a surface

• Full inventory query → registry (snippets-index.json).
• Type-scoped query with install commands → specialized index (components|sections|templates-index.json).
• Name/description/tag search → the registry (snippets-index.json).
• "What is installed in this project?" → devsnips/config.json.
• Deep truth about one resource → the resource's own metadata.json at library/<path> (registry copies can lag).

Consumers

• CLI — fetches the registry from GitHub main and resolves npx devsnips add <path> against variants[].path. See CLI overview.
• Validation — validate.py requires two-way registry↔disk agreement; rebuild_index.py refuses to write on mismatch.
• Agents — the skill and the per-type indexes both require reading the live registry rather than trusting documentation.

Pages in this section

For integrators

There is no HTTP API. Consume the JSON files directly (raw GitHub URLs or your own mirror of the repository). The registry URL used by the CLI:

https://raw.githubusercontent.com/sarthakbystander/DevSnips/main/snippets-index.json

Pin your integration to a commit rather than main if you need reproducibility; main is the live truth the CLI itself uses.

Go deeper

This page is the human-facing machine-readable overview. The implementation-anchored reference (generator internals, the full specialized-index schema, and the leaf-detection parity contract) is maintained for agents in agents/resources/indexing.md.