feat: add specify artifact command exposing composition stacks as JSON

docs/reference/presets.md

@@ -205,6 +205,25 @@ specify preset add team-workflow --priority 10
 
 For any file that both provide, `compliance` wins (priority 5 < 10). For files only one provides, that one is used. For files neither provides, the core default is used.
 
+## Contribution Identifiers
+
+Every command, template, and script contributed by a preset (or an extension, or the core layer) is addressable at read time by a deterministic opaque identifier of the form:
+
+```text
+{layer}:{sourceId}:{kind}:{name}
+```
+
+- `layer` is one of `core`, `preset`, or `extension`.
+- `sourceId` is `_` for `core`, the preset pack id for `preset`, or the extension id for `extension`.
+- `kind` is one of `command`, `template`, or `script`.
+- `name` is the entry's declared `name` field.
+
+Identifiers are computed on demand from author-declared manifest content and are never persisted to `.specify/` or any cache. Copying a preset to another machine (or touching its files) does not change the identifiers it produces.
+
+`PresetResolver.collect_all_layers()` returns layer dicts that each include a `lookupId` field pointing back to the originating contribution's `id`. Project-local overrides in `.specify/templates/overrides/` are a resolver-only concept — they carry a synthetic `project:_:{kind}:{name}` `lookupId` that intentionally does not match any manifest contribution.
+
+For the full grammar, including the hook name-component convention and the discriminator recipe used by extensions, see the [Extension API Reference — Contribution Identifiers](../../extensions/EXTENSION-API-REFERENCE.md#contribution-identifiers) section.
+
 ## FAQ
 
 ### Can I use multiple presets at the same time?

extensions/EXTENSION-API-REFERENCE.md

@@ -10,6 +10,7 @@ Technical reference for Spec Kit extension system APIs and manifest schema.
 4. [Configuration Schema](#configuration-schema)
 5. [Hook System](#hook-system)
 6. [CLI Commands](#cli-commands)
+7. [Contribution Identifiers](#contribution-identifiers)
 
 ---
 
@@ -859,7 +860,60 @@ satisfied = version_satisfies("1.2.3", ">=1.0.0,<2.0.0")  # bool
 
 ---
 
-## File System Layout
+## Contribution Identifiers
+
+Every command, template, script, and hook contributed by an extension (or a preset, or the core layer) is addressable at read time by a deterministic opaque identifier. Resolved artifact-stack layers carry a matching `lookupId` field that points back to the contribution the layer came from. Identifiers are **computed on demand from author-declared manifest content** and are **never persisted** to `.specify/` or to any cache file.
+
+### Grammar
+
+Named contributions (commands, templates, scripts) follow:
+
+```text
+{layer}:{sourceId}:{kind}:{name}
+```
+
+- `layer` is one of `core`, `preset`, or `extension`.
+- `sourceId` is `_` for `core`, the preset pack id for `preset`, or the extension id for `extension`.
+- `kind` is one of `command`, `template`, `script`, or `hook`.
+- `name` is the contribution's declared `name` field.
+
+Hook contributions use a compound name-component built from the event and command:
+
+```text
+{layer}:{sourceId}:hook:{eventName}:{command}
+```
+
+When two or more hook entries within the same source share the same `(eventName, command)` pair, a 12-hex-character discriminator is appended:
+
+```text
+{layer}:{sourceId}:hook:{eventName}:{command}:{discriminator}
+```
+
+The discriminator is the first 12 lowercase hex characters of `sha256(canonical_json(entry - {eventName, command}))`. If two entries are byte-identical after removing `eventName` and `command`, they collapse under the existing per-event, per-command last-write-wins hook merge semantics.
+
+### Reserved character
+
+`:` is reserved as the identifier component separator. It cannot appear inside any of `layer`, `sourceId`, `kind`, `name`, `eventName`, or `command`. Extension ids, command names, template names, and script names are already constrained by their existing regex patterns (`^[a-z0-9-]+$` and friends), which forbid `:`. Hook event names (mapping keys) and hook `command` values are additionally validated to reject `:` at manifest load.
+
+### The `project:` sentinel
+
+Project-local overrides in `.specify/templates/overrides/` are a resolver-only concept — they have no backing manifest and cannot appear in `iter_contributions()`. Layers of that kind carry a synthetic `lookupId` of the form `project:_:{kind}:{name}` so consumers that reverse-lookup the id always see "not found", which is the intended behaviour: overrides are addressable at the stack level, not as first-class contributions.
+
+### Python API
+
+`ExtensionManifest.iter_contributions()` yields dicts of the form `{layer, sourceId, kind, name, id, ...author-declared fields}`; each entry's `id` is the computed identifier. `ExtensionManifest.contribution_id(kind, name)` returns the id for a single lookup, or `None` if no contribution matches. `PresetManifest` exposes the same two methods.
+
+`PresetResolver.collect_all_layers()` returns layer dicts that include a `lookupId` field for every layer type (`project override`, preset, extension, core, and bundled core). Resolver `lookupId` values identify the layer by the resolver's registry key or directory name, which can differ from the manifest-declared source id used by `iter_contributions()`.
+
+### Determinism guarantees
+
+Manifest contribution identifier derivation reads only the in-memory declared manifest content. No filesystem paths, no `os.environ`, no timestamps, and no file-content hashes contribute to those manifest ids. Copying an extension or preset to a different machine (or touching its files) does not change the identifiers it produces. Resolver `lookupId` values are stack identifiers, not manifest contribution ids: for example, an unregistered extension's directory name is the resolver source id, so renaming that directory changes its `lookupId`.
+
+### Opacity guidance
+
+Identifiers are stable, but treat them as **opaque strings** in stored data (registries, cache files, external tooling). Do not parse them by string-splitting on `:` — the discriminator suffix and future grammar extensions may otherwise catch you out. If you only need to classify a stack entry's layer, use `layer_kind_from_lookup_id`; `derive_named_id` and `derive_hook_id` construct new identifiers rather than parsing existing ones.
+
+
 
 ```text
 .specify/

src/specify_cli/__init__.py

@@ -560,6 +560,13 @@ def _require_specify_project() -> Path:
 _register_preset_cmds(app)
 
 
+# ===== Artifact Commands =====
+
+# Read-only introspection over the composed inventory (commands/templates/scripts).
+from .artifacts._commands import register as _register_artifact_cmds  # noqa: E402
+_register_artifact_cmds(app)
+
+
 # ===== Bundle Commands =====
 
 # Bundler subcommand group (specify bundle ...) — see commands/bundle/.

src/specify_cli/_assets.py

@@ -32,6 +32,32 @@ def _repo_root() -> Path:
     return Path(__file__).parent.parent.parent
 
 
+def _locate_core_asset_dir(subdir: str) -> Path | None:
+    """Return the on-disk directory holding a family of core assets, or None.
+
+    ``subdir`` is one of ``"commands"``, ``"templates"``, or ``"scripts"`` —
+    the three asset families every core baseline consumer needs to agree on.
+    Prefers the wheel-installed ``core_pack`` bundle, then falls back to the
+    source-checkout layout. This is the single place that knows the two-tier
+    resolution ("wheel bundle, else repo-root checkout") for locating core
+    assets, so callers (extension command-name discovery, the preset
+    resolver's core fallback, and the artifact command's core-baseline
+    enumeration) cannot silently diverge on what "core" means on a given
+    machine.
+    """
+    if subdir not in ("commands", "templates", "scripts"):
+        return None
+    core = _locate_core_pack()
+    if core is not None:
+        candidate = core / subdir
+        return candidate if candidate.is_dir() else None
+    if subdir == "commands":
+        candidate = _repo_root() / "templates" / "commands"
+    else:
+        candidate = _repo_root() / subdir
+    return candidate if candidate.is_dir() else None
+
+
 def _locate_bundled_extension(extension_id: str) -> Path | None:
     """Return the path to a bundled extension, or None.
 

src/specify_cli/_identifier.py

@@ -0,0 +1,210 @@
+"""Deterministic identifiers for Spec Kit contributions and resolved stack layers.
+
+Every command, template, script, and hook contribution surfaced by a preset or
+extension manifest carries a computed opaque ``id`` string, and every layer of a
+resolved artifact stack carries a matching ``lookupId``. The identifier value is
+derived only from author-declared manifest data — it never depends on file
+contents, timestamps, archive hashes, installation directory paths, install-time
+random values, or list positions. That is what makes identifiers portable
+across machines, project locations, and reinstalls, and what lets consumers use
+them as stable join keys.
+
+Grammar for named contributions (commands, templates, scripts)::
+
+    id = "{layer}:{sourceId}:{kind}:{name}"
+
+    layer    ∈ {"core", "preset", "extension"}
+    sourceId = "_" when layer == "core"; the preset id or extension id otherwise
+    kind     ∈ {"command", "template", "script", "hook"}
+    name     = the contribution's declared ``name``
+
+Hook identifiers use ``{eventName}:{command}`` as the name component::
+
+    id = "{layer}:{sourceId}:hook:{eventName}:{command}[:{discriminator}]"
+
+The 12-lowercase-hex discriminator is appended only when at least one sibling
+hook in the same source shares the same ``(eventName, command)`` pair, and it is
+computed by SHA-256 of a canonical JSON serialization of the hook entry's
+declared fields (with ``eventName`` and ``command`` removed, since they already
+appear in the identifier prefix).
+
+The functions in this module are pure — inputs are strings or in-memory
+mappings parsed from a manifest, outputs are strings. None of them read from
+disk, look at ``os.environ``, call ``datetime``, or hash file contents. That
+guarantee is what preserves portability, and it is enforced by inspection
+rather than by runtime checks: any change here that adds an ambient input is a
+change that breaks the identifier contract.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Iterable, Mapping
+
+
+PROJECT_OVERRIDE_LAYER = "project"
+"""Resolver-only layer label for project-local override layers.
+
+Project overrides are a resolver feature — they are not backed by any manifest
+contribution. When a resolved artifact stack contains a project-override layer,
+its ``lookupId`` uses this label so the round-trip invariant (every layer
+carries a ``lookupId``) still holds. No manifest ``iter_contributions()`` will
+ever emit a matching ``id``, so consumers see "not found" for the lookup, which
+is the correct outcome for a layer with no originating manifest entry.
+"""
+
+_DISCRIMINATOR_LENGTH = 12
+
+
+class IdentifierComponentError(ValueError):
+    """Raised when a manifest component would break identifier grammar."""
+
+
+def validate_component(value: Any, field_label: str) -> str:
+    """Return ``value`` unchanged if it is a non-empty ``:``-free string.
+
+    Manifest components that appear in an identifier (``layer``, ``sourceId``,
+    ``kind``, ``name``, ``eventName``, ``command``) may not contain the ``:``
+    delimiter — the grammar has no escape rule. This function is the guard used
+    by manifest validators to reject offending values at load time with a clear
+    message naming the field.
+    """
+    if not isinstance(value, str):
+        raise IdentifierComponentError(
+            f"Invalid {field_label}: expected a string, got {type(value).__name__}"
+        )
+    if not value:
+        raise IdentifierComponentError(
+            f"Invalid {field_label}: value must not be empty"
+        )
+    if ":" in value:
+        raise IdentifierComponentError(
+            f"Invalid {field_label} '{value}': ':' is reserved as an identifier delimiter"
+        )
+    return value
+
+
+def derive_named_id(layer: str, source_id: str, kind: str, name: str) -> str:
+    """Build the identifier string for a named contribution kind.
+
+    Callers are expected to have already validated each component with
+    :func:`validate_component` at manifest-load time; this function does not
+    revalidate — it is a pure string join so the identifier can be computed
+    cheaply on every read.
+    """
+    return f"{layer}:{source_id}:{kind}:{name}"
+
+
+_LAYER_KINDS = frozenset({"core", PROJECT_OVERRIDE_LAYER, "preset", "extension"})
+
+
+def layer_kind_from_lookup_id(lookup_id: str) -> str | None:
+    """Return the layer segment of a resolved-stack ``lookupId``, or ``None``.
+
+    ``lookupId`` values on resolved stack layers follow the same
+    ``"{layer}:..."`` grammar as manifest-contribution ``id`` values (see
+    module docstring), with ``layer`` additionally taking on
+    :data:`PROJECT_OVERRIDE_LAYER` for resolver-only project-override layers.
+    This is the single place that knows the set of valid layer prefixes, so
+    consumers can classify a lookupId without re-deriving the grammar via
+    string-prefix checks of their own.
+    """
+    layer, _, rest = lookup_id.partition(":")
+    if not rest or layer not in _LAYER_KINDS:
+        return None
+    return layer
+
+
+def is_dotted_command_name(value: str) -> bool:
+    """Return ``True`` when ``value`` is a dotted command-style name.
+
+    Command-style names allow lowercase alphanumerics and ``-`` in each segment
+    and require at least one ``.`` separator.
+    """
+    if "." not in value:
+        return False
+    segments = value.split(".")
+    return all(
+        segment
+        and all((("0" <= char <= "9") or ("a" <= char <= "z") or char == "-") for char in segment)
+        for segment in segments
+    )
+
+
+def canonical_json(value: Any) -> bytes:
+    """Serialize ``value`` to a canonical UTF-8 JSON byte string.
+
+    Mapping keys are sorted lexicographically at every depth, list order is
+    preserved (author intent), whitespace is stripped, and non-ASCII characters
+    are emitted verbatim. This is the byte string the hook discriminator hashes.
+    """
+    normalized = _normalize_for_canonical_json(value)
+    return json.dumps(
+        normalized,
+        sort_keys=True,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def _normalize_for_canonical_json(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {str(k): _normalize_for_canonical_json(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_normalize_for_canonical_json(v) for v in value]
+    return value
+
+
+def _has_hook_sibling_collision(
+    event_name: str,
+    command: str,
+    siblings: Iterable[Mapping[str, Any]],
+) -> bool:
+    """Return True when at least one sibling shares the same event/command pair.
+
+    ``siblings`` is the full same-source hook entry list including the entry
+    whose identifier is being derived. A collision therefore means at least two
+    entries share the pair.
+    """
+    seen = 0
+    for entry in siblings:
+        if entry.get("eventName") == event_name and entry.get("command") == command:
+            seen += 1
+            if seen >= 2:
+                return True
+    return False
+
+
+def hook_discriminator(declared_fields: Mapping[str, Any]) -> str:
+    """Compute the 12-hex-char SHA-256 discriminator for a hook entry.
+
+    ``declared_fields`` is the entry as parsed from the manifest with
+    ``eventName`` and ``command`` removed — those two values already appear in
+    the identifier prefix, so hashing them would only reflect information the
+    consumer can already read.
+    """
+    return hashlib.sha256(canonical_json(declared_fields)).hexdigest()[:_DISCRIMINATOR_LENGTH]
+
+
+def derive_hook_id(
+    layer: str,
+    source_id: str,
+    event_name: str,
+    command: str,
+    siblings: Iterable[Mapping[str, Any]],
+    own_declared_fields: Mapping[str, Any],
+) -> str:
+    """Build the identifier string for a hook contribution.
+
+    The discriminator suffix is appended only when at least one sibling in the
+    same source shares the same ``(event_name, command)`` prefix. That keeps the
+    common case terse and the collision case unambiguous. ``siblings`` must
+    include every hook entry declared under this source (including the one
+    whose identifier is being derived); the function decides on its own whether
+    a collision exists.
+    """
+    base = f"{layer}:{source_id}:hook:{event_name}:{command}"
+    if _has_hook_sibling_collision(event_name, command, siblings):
+        return f"{base}:{hook_discriminator(own_declared_fields)}"
+    return base

src/specify_cli/_script_variants.py

@@ -0,0 +1,32 @@
+"""Canonical names and paths for the core script runtime variants."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+_SCRIPT_VARIANTS = (
+    ("bash", ".sh", False),
+    ("powershell", ".ps1", False),
+    ("python", ".py", True),
+)
+
+
+def canonical_script_name(path: Path) -> str | None:
+    """Return the logical name shared by a core script's runtime variants."""
+    for runtime, suffix, uses_underscores in _SCRIPT_VARIANTS:
+        if path.parent.name == runtime and path.suffix == suffix:
+            return path.stem.replace("_", "-") if uses_underscores else path.stem
+    return None
+
+
+def script_variant_paths(scripts_dir: Path, name: str) -> Iterator[Path]:
+    """Yield candidate paths for the logical script *name*.
+
+    The legacy flat Bash path (``<scripts_dir>/<name>.sh``) is yielded first so
+    existing projects keep working, followed by the runtime-specific paths.
+    """
+    yield scripts_dir / f"{name}.sh"
+    for runtime, suffix, uses_underscores in _SCRIPT_VARIANTS:
+        stem = name.replace("-", "_") if uses_underscores else name
+        yield scripts_dir / runtime / f"{stem}{suffix}"