[Bug]: Preset script artifacts cannot be resolved to usable paths through the CLI

[nicolehaugen]

Bug Description

Preset-provided scripts can be registered and discovered as artifacts, but the CLI does not expose an effective, ready-to-load script path. In Specify 1.0.7, specify preset resolve <name> reports "not found" for a named .mjs adapter registered with type: script. The same file resolves successfully when registered with type: template.

This blocks a Designer integration that already uses specify preset resolve <name> to locate page templates and needs to locate preset-provided JavaScript adapters through Specify's resolution stack. Consumers should not have to implement their own priority resolution or script composition.

Steps to Reproduce

1. In an initialized Specify project, create a local preset with an adapters/page-adapter.mjs file and the following manifest:

   schema_version: "1.0"
   preset:
     id: designer-adapter-repro
     name: Designer Adapter Repro
     version: "1.0.0"
     description: Reproduce preset script lookup
   requires:
     speckit_version: ">=1.0.7"
   provides:
     templates:
       - type: script
         name: designer-page-adapter
         file: adapters/page-adapter.mjs
         strategy: replace

2. Install it with specify preset add --dev ./designer-adapter-repro.

3. Run specify preset resolve designer-page-adapter.

4. Inspect the registered script using specify artifact info --json with the appropriate script artifact identifier.

5. As a control, change the entry's type to template, reinstall the preset, and resolve the same logical name again.

The reporting user tested the script-versus-template behavior on Specify 1.0.7. The minimal fixture above illustrates that report; it has not been independently executed during issue preparation.

Expected Behavior

A consumer should have a Specify-owned CLI interface to resolve a registered script by logical name, respecting the enabled resolution stack and priority.

For strategy: replace, it should expose the winning script's usable path. For supported composition, Specify should own composition and provide an explicitly documented way to obtain usable output, rather than requiring consumers to reconstruct it from artifact metadata.

This could be an explicit script-type option on a resolver or a dedicated artifact-resolution command; it need not change the existing template-only command's default behavior. Any materialization contract for JavaScript modules should also document module-relative import behavior.

Actual Behavior

• A .mjs adapter registered as type: script is reported as "not found" by specify preset resolve <name>.
• specify artifact info --json identifies contributing packages but does not give Designer a ready-to-load composed script path.
• Registering the same file as a named type: template asset allows preset resolve to locate it.

Specify CLI Version

1.0.7 (reported by the user)

AI Agent

Not applicable — CLI artifact resolution for a Designer integration.

Operating System

Not reported for the user's reproduction.

Python Version

Not reported for the user's reproduction.

Error Logs

User-reported result; a full command transcript was not supplied:

specify preset resolve <script-name>
# Reports: not found

Additional Context

Inspection of the current default branch explains the lookup behavior:

• command_resolve.py selects command for dotted names and template otherwise; it never selects script.
• _resolver.py supports Python-level resolve(name, "script") and resolve_content(name, "script"). The former returns a source path rather than materialized composition; the latter returns composed text. This is not a CLI ready-to-load module-path contract. These observations concern the current branch, not an independently verified 1.0.7 Python API.
• _manifest.py accepts script entries with replace or wrap strategies.
• The bundled Lean preset registers command prompts, not script artifacts. The scaffold command references existing core shell/PowerShell scripts through command frontmatter, which is distinct from resolving preset-provided script artifacts.
• presets/scaffold/preset.yml still labels its commented-out script artifact example "reserved for future use", whereas the preset documentation describes script composition support. Clarifying the supported consumption path would help.

Current workaround: register the JavaScript adapter as a named template asset with strategy: replace. This permits existing CLI lookup but misclassifies executable code as a template. Directly loading a known installed preset file also bypasses stack resolution and is not an equivalent solution.

Even template resolution can display a contributing layer's path rather than a materialized composed result, so this report is not proposing that consumers treat any displayed layer path as composed output.

AI Disclosure

Prepared by GitHub Copilot in Auto mode, human-supervised, from the user's reported Specify 1.0.7 behavior and read-only inspection of the repository's current default branch. Auto mode selected the underlying model; its identity and reasoning-effort setting were not available. AI assistance covered repository investigation and drafting/submitting this issue. No independent runtime reproduction was performed.

[github-actions]

Bug assessment — preset-script-resolution: Valid · severity medium

---

Bug Assessment: Preset script artifacts cannot be resolved to usable paths through the CLI

• Slug: preset-script-resolution
• Created: 2026-10-02T17:32:33Z
• Source: issue [Bug]: Preset script artifacts cannot be resolved to usable paths through the CLI #4819
• Verdict: valid
• Severity: medium

Report (summarized)

The reporter says a preset manifest can register a JavaScript adapter as a type: script artifact, but specify preset resolve <name> reports it as not found. The same file resolves when misclassified as type: template. specify artifact info --json exposes contributing layers/provenance but not a ready-to-load composed module path. This blocks a Designer integration that needs stack-aware script resolution. The report concerns Specify 1.0.7; no independent runtime transcript was supplied.

Symptom

A manifest-declared script is supported by the preset/artifact model but is invisible to the human-facing preset resolve command, which only chooses template or command resolution. Even through the artifact API, composition is represented as content/provenance rather than a materialized JavaScript module path, so consumers cannot obtain the requested effective load target without reimplementing resolution.

Reproduction

1. Create a preset containing adapters/page-adapter.mjs and declare it under provides.templates with type: script, logical name designer-page-adapter, and strategy: replace.
2. Install it with specify preset add --dev ./designer-adapter-repro.
3. Run specify preset resolve designer-page-adapter.
4. Observe that the command uses template resolution and reports no layer, while the same declaration as type: template is discoverable.
5. Inspect specify artifact info script:designer-page-adapter --json (or the equivalent script kind/name form) to see the stack/provenance rather than a composed, ready-to-load module output.

The report does not provide the exact full command transcript or the user's operating system/Python version: [NEEDS CLARIFICATION: confirm the precise 1.0.7 output and environment if maintainers need a runtime regression test].

Suspected Code Paths

• src/specify_cli/presets/command_resolve.py:15-43 — preset_resolve validates the name and unconditionally maps dotted names to command, all other names to template; it never selects script.
• src/specify_cli/presets/command_resolve.py:43-108 — the command calls collect_all_layers/resolve_with_source only with that template/command type, so a valid script layer is not queried.
• src/specify_cli/presets/_resolver.py:223-378 — the resolver already accepts template_type == "script", including explicit manifest files and script paths, but convention fallback is shell-oriented (.sh, with callers expected to handle other variants), showing the lower-level capability is separate from the CLI surface.
• src/specify_cli/presets/_resolver.py:507-735 — collect_all_layers and resolve_content implement script stack discovery and composition, including $CORE_SCRIPT for wraps.
• src/specify_cli/artifacts/catalog.py:904-936 — artifact inventory includes preset script declarations, so scripts are an exposed artifact kind rather than rejected metadata.
• docs/reference/artifacts.md:1-5,81-95,132-148 — documentation defines scripts as first-class artifacts and documents stack/provenance, but does not define a command or materialization contract for loading a composed script module.

Root Cause Hypothesis

Confidence: high. The immediate lookup failure is a CLI dispatch gap: preset resolve has no script-kind option or inference path, despite PresetResolver and ArtifactCatalog supporting script layers. The ready-to-load module-path issue is a second contract gap: resolve_content(..., "script") returns composed text, while artifact stack rows expose contributing sourcePath values, not a materialized composed file. The current implementation therefore cannot satisfy a consumer that needs one effective module path for non-replace composition.

Proposed Remediation

Preferred: Extend the resolution surface with an explicit script-aware operation, such as specify preset resolve <name> --kind script or a dedicated specify artifact resolve <kind:name> command. For replace, return the winning validated source path. For wrap/prepend/append, add an explicit materialization operation that writes composed content to a deterministic project/cache output and returns that path; document whether module-relative imports resolve relative to the materialized file, the winning layer, or require import rewriting. Reuse PresetResolver.collect_all_layers and resolve_content rather than duplicating priority logic, and keep the existing template-only default behavior unchanged.

Alternatives:

• Add only script support to preset resolve, returning the top layer path and clearly warning that composed output is not that path. This is smaller but does not meet the integration's ready-to-load requirement for composition.
• Expose a library/API method returning composed bytes plus provenance and let consumers materialize them. This avoids CLI filesystem policy but still requires every consumer to define path/import semantics.

Files likely to change:

• src/specify_cli/presets/command_resolve.py
• src/specify_cli/presets/_resolver.py or a shared artifact materialization helper
• src/specify_cli/artifacts/command_info.py / artifact command registration if a dedicated command is chosen
• docs/reference/presets.md
• docs/reference/artifacts.md
• tests/specify_cli/presets/test_command_resolve.py
• tests/specify_cli/artifacts/test_command_info.py and/or catalog tests

Tests to add or update:

• A CLI test proving --kind script resolves an explicit manifest-declared .mjs file and honors preset priority.
• Negative coverage proving the default template lookup still does not silently reinterpret arbitrary names as scripts and that invalid kinds are rejected clearly.
• Composition tests for script replace, wrap, prepend, and append, including the returned materialized path/content contract and module-relative import behavior.
• Artifact command tests verifying script stack provenance remains accurate and that materialized output is distinguishable from a contributing source path.

Risks & Considerations

• Returning a source path for a composed script would be incorrect; materialization needs lifecycle, cleanup, and collision rules.
• JavaScript module-relative imports can break when composed output is placed outside the original preset directory; this must be documented or handled explicitly.
• A new CLI option/command is additive, but changing preset resolve's default inference could alter existing template behavior.
• .mjs support should be validated independently from the resolver's existing shell-script convention and should not broaden manifest path access beyond current containment checks.

Open Questions

• [NEEDS CLARIFICATION: Should the public contract cover only strategy: replace script paths, or must composed scripts always be materialized?]
• [NEEDS CLARIFICATION: What import/base-directory semantics does Designer require for a composed .mjs module?]
• [NEEDS CLARIFICATION: Should the command accept --kind script, a script:<name> identifier, or a separate artifact-resolution command?]
• [NEEDS CLARIFICATION: Confirm the exact Specify 1.0.7 command output and environment if a release-specific regression must be distinguished from the current behavior.]

Generated by 🐛 Assess Bug from Labeled Issue for #4819 · copilot · gpt52codex · 2.36 AIC · ⌖ 5.7 AIC · ⊞ 21.8K · ◷