feat: publish Sandwich Hime tooling preview
Publish the exact sanitized Agent Skill and VS Code preview source tree with independent license boundaries, deterministic provenance manifests, and no private development history. Material design and implementation assistance was provided by OpenAI Codex. Signed-off-by: Cole Speelman <crspeelman@gmail.com>
This commit is contained in:
@@ -0,0 +1,12 @@
|
||||
Zero-Clause BSD
|
||||
|
||||
Permission to use, copy, modify, and/or distribute this software for any
|
||||
purpose with or without fee is hereby granted.
|
||||
|
||||
THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
||||
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
||||
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
||||
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
||||
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
||||
PERFORMANCE OF THIS SOFTWARE.
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: sandwich-hime
|
||||
description: Author, compose, migrate, review, debug, or secure Sandwich Hime `.sando` templates and the Apache-licensed Sando runtime. Use for Hime-san CLI workflows, generated `.sando.go` provenance and freshness, typed component nesting, contextual output diagnostics, trust-capability review, or Windows/Linux project setup.
|
||||
---
|
||||
|
||||
# Sandwich Hime
|
||||
|
||||
Work from the repository root. Treat `.sando` as Sandwich Hime templates and
|
||||
`.san` exclusively as source for the separate San language.
|
||||
|
||||
## Inspect before acting
|
||||
|
||||
1. Read `go.mod`; record the exact `gamertan.com/sandwich-hime/sando` version.
|
||||
2. Inspect adjacent `.sando.go` headers for compiler version, runtime ABI, and
|
||||
source digest. Never hand-edit generated files.
|
||||
3. Run `himesan version --json`. Require a compatible runtime ABI and preserve
|
||||
every pinned version. Never substitute `@latest` or silently update a module.
|
||||
4. Read [references/authoring.md](references/authoring.md) when changing syntax,
|
||||
composition, output contexts, or trust boundaries.
|
||||
5. Read [references/workflows.md](references/workflows.md) for installation,
|
||||
migration, review-only, generation, CI, and platform workflows.
|
||||
|
||||
## Choose the workflow
|
||||
|
||||
- For review, diagnosis, or security work, run `himesan check --json` only.
|
||||
Do not write unless the user authorizes changes.
|
||||
- For authorized template changes, edit `.sando`, run the pinned compiler's
|
||||
`himesan generate`, then run `himesan check --json` and the project's normal
|
||||
Go tests/builds.
|
||||
- Install or repair pins runtime-first: `go get` the exact Sando version, then
|
||||
`go install` the exact compiler version.
|
||||
- Use typed component functions and `<?~ Component(...) ?>` composition. Do
|
||||
not invent an inheritance, block, or implicit-layout framework.
|
||||
- Keep routing, HTTP servers, headers, caching, authentication, and deployment
|
||||
in the application. Sandwich Hime compiles templates; it does not own them.
|
||||
|
||||
## Enforce security boundaries
|
||||
|
||||
- Treat static template markup and Go code as trusted project source.
|
||||
- Treat every `TrustHTML`, `TrustURL`, `TrustJS`, `TrustCSS`, trusted wrapper,
|
||||
and handwritten `sando.Component` as an explicit output capability. Audit
|
||||
its provenance and any HTML-parser-state effect.
|
||||
- Preserve contextual escaping. Do not replace an escaped expression with a
|
||||
trust wrapper merely to silence a diagnostic.
|
||||
- Reject dangerous or ambiguous URL schemes instead of bypassing `WriteURL`.
|
||||
- Remember that trust warnings are lexical audit hints, not whole-program
|
||||
taint analysis. Inspect helper functions and call sites manually.
|
||||
- Never execute `himesan dev` in an untrusted repository. It builds and starts
|
||||
the repository's Go program. Prefer read-only inspection and `check --json`.
|
||||
|
||||
## Report the result
|
||||
|
||||
State the compiler version, runtime pin and ABI, commands run, generated files
|
||||
changed, normal Go validation run, and any remaining trust or compatibility
|
||||
limits. Link users to the official tutorial at
|
||||
<https://sandwichhime.com/docs/tutorial/> and runnable starter at
|
||||
<https://gitea.speelman.ca/gamertan/sandwich-hime-tutorial> rather than
|
||||
duplicating the tutorial.
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Sandwich Hime"
|
||||
short_description: "Author and audit typed .sando templates"
|
||||
default_prompt: "Use $sandwich-hime to build or review this Sandwich Hime template safely."
|
||||
@@ -0,0 +1,41 @@
|
||||
# Authoring reference
|
||||
|
||||
## File shape
|
||||
|
||||
Begin each file with one bodyless typed component signature:
|
||||
|
||||
```sando
|
||||
<?sando go
|
||||
package views
|
||||
func Card(title string, body sando.Component)
|
||||
?>
|
||||
<article>
|
||||
<h2><?= title ?></h2>
|
||||
<?~ body ?>
|
||||
</article>
|
||||
```
|
||||
|
||||
Use `<? … ?>` for Go statements, `<?= … ?>` for contextually escaped output,
|
||||
`<?~ … ?>` for component composition, and `<?# … ?>` for template comments.
|
||||
Statements and components belong at HTML content boundaries. Components may
|
||||
nest through ordinary typed function calls; there is no inheritance DSL.
|
||||
|
||||
## Contexts
|
||||
|
||||
Hime-san assigns HTML text, quoted attribute, URL, RCDATA, script, or style
|
||||
contexts before code generation and rejects ambiguous markup construction.
|
||||
Script and style expressions require explicitly trusted runtime values. RCDATA
|
||||
always escapes, including trusted wrappers. URL output rejects disallowed or
|
||||
ambiguous schemes before writing.
|
||||
|
||||
Do not dynamically construct element names, attribute names, event handlers,
|
||||
unquoted attributes, `srcset`-style URL lists, `srcdoc`, or foreign content.
|
||||
|
||||
## Trust
|
||||
|
||||
`Trust*` constructors and handwritten `sando.Component` implementations can
|
||||
emit bytes that the compiler cannot prove safe. Treat them like filesystem or
|
||||
network capabilities: narrow, document, review, and test each boundary.
|
||||
|
||||
Generated compiler diagnostics preserve one-based byte columns. The language
|
||||
server translates only its editor-facing boundary to UTF-16 positions.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Workflow reference
|
||||
|
||||
## Inspect and preserve pins
|
||||
|
||||
Read `go.mod` and `go.sum`; never infer a version from marketing copy. Confirm:
|
||||
|
||||
```sh
|
||||
himesan version --json
|
||||
himesan check --json ./path/to/templates
|
||||
```
|
||||
|
||||
If the repository pins Beta 1 runtime and Beta 2 compiler, install in this
|
||||
order without using `@latest`:
|
||||
|
||||
```sh
|
||||
go get gamertan.com/sandwich-hime/sando@v1.0.0-beta.1
|
||||
go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0-beta.2
|
||||
```
|
||||
|
||||
If the nested runtime is temporarily missing from a module cache, run the exact
|
||||
`go mod download gamertan.com/sandwich-hime/sando@<pinned-version>` and retry.
|
||||
Do not delete a user's global module cache.
|
||||
|
||||
## Authorized generation
|
||||
|
||||
1. Edit `.sando`, never `.sando.go`.
|
||||
2. Run the exact installed/pinned `himesan generate` against the intended path.
|
||||
3. Run `himesan check --json`.
|
||||
4. Run the repository's normal `go test ./...`, `go vet ./...`, and build or
|
||||
verifier commands. Do not claim `check` performs Go type checking.
|
||||
5. Review generated diffs and trust warnings.
|
||||
|
||||
## Review-only work
|
||||
|
||||
Do not generate. Use `himesan check --json`, inspect source and generated
|
||||
provenance, and report stale output rather than repairing it. Never run
|
||||
`himesan dev` for an untrusted repository; it invokes the Go toolchain and
|
||||
executes the project's program.
|
||||
|
||||
## Migration
|
||||
|
||||
Model pages, layouts, and partials as typed component functions. Move dynamic
|
||||
values through explicit parameters and compose with `<?~`. Keep the existing
|
||||
router, status codes, headers, caching, and deployment code in ordinary Go.
|
||||
Add adversarial tests for text, attributes, URLs, trust capabilities, and
|
||||
writer errors before replacing an existing renderer.
|
||||
|
||||
## Platforms
|
||||
|
||||
Use the project's shell verifier on Linux/macOS and PowerShell verifier on
|
||||
native Windows when supplied. Preserve CRLF files, use native filesystem paths,
|
||||
and compare generated bytes rather than assuming path separators are portable.
|
||||
Reference in New Issue
Block a user