jakeryderv-pi-artifacts-jakeryderv

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# @jakeryderv/pi-artifacts

Rich visualization artifacts for the [Pi coding agent](https://pi.dev/). Scaffold,
validate, and preview artifact bundles — portable markdown documents and an
interactive html stack (declarative components, Pico CSS, and CSP-clean
Chart.js) — in a session-scoped viewer.

> **Status: markdown + declarative html, live viewer + single-file export.** The package can scaffold markdown
> and html artifact bundles, validate/normalize them, serve localhost previews,
> and show a session-scoped browser gallery via `/viewer` that updates live
> (Server-Sent Events) as artifacts are rendered or deleted — and open artifact
> pages reload themselves when re-rendered. html artifacts get a shared runtime
> (Pico CSS, components, file-backed feeds, Chart.js, Mermaid, icons) injected
> under a strict CSP. See
> the [roadmap](https://github.com/jakeryderv/pi-artifacts/blob/main/docs/roadmap.md),
> [API contract](https://github.com/jakeryderv/pi-artifacts/blob/main/docs/api.md),
> and [design notes](https://github.com/jakeryderv/pi-artifacts/blob/main/docs/notes/design.md)
> for the broader plan.

## What's new in 0.9.1

Maintenance release — no artifact-authoring behavior changed.

- **Corrected package metadata.** `repository` and `homepage` now point at
  `github.com/jakeryderv/pi-artifacts`; the 0.9.0 metadata still referenced the
  former monorepo path, so the links on npm resolved to a missing directory.
- Releases are now published from CI on a `v*` tag using npm trusted publishing,
  so this and later versions carry a provenance attestation.

## What's new in 0.9.0

- **Portable single-file HTML export** for both markdown and html artifacts via
  `export_artifact` or the viewer's per-artifact Export action.
- Package runtime CSS/JavaScript, KaTeX fonts, icons, referenced images, and
  artifact-local JSON feeds are embedded into the exported document.
- Exports carry their own restrictive CSP, authorize only embedded package-owned
  runtime scripts, and remove authored executable scripts, event handlers, and
  `javascript:` URLs.

## What's new in 0.8.1

- **Correct Markdown math boundaries**: KaTeX rendering now operates on parsed
  Markdown text tokens, preserving dollar-delimited text inside inline and fenced
  code as code and avoiding ambiguous currency pairs.
- **Safer store operations**: artifact IDs must be one generated slug segment,
  and concurrent manifest updates use independent atomic temporary files.
- **Dependency hardening**: the minimum `markdown-it` version is raised to the
  patched 14.3 release line.

## What's new in 0.8.0

- **Declarative HTML components**: package-owned `<pi-grid>`, `<pi-card>`,
  `<pi-metric>`, `<pi-chart>`, and `<pi-table>` Web Components provide a
  consistent dashboard vocabulary without authored JavaScript or a build step.
- **Artifact-local data feeds**: `<pi-data-source>` loads one-shot JSON snapshots
  from the bundle's `assets/` directory and binds them to metrics, charts, and
  tables with `data-feed` and optional dotted `field` paths.
- **Viewer hardening**: artifact content, gallery pages, and SSE now use a random
  per-server capability path; the preview server starts lazily and adds no-store
  and same-origin resource headers.
- **Cleaner internals and launcher lifecycle**: renderer selection is centralized
  in a typed registry, while app mode tracks Chromium liveness, launch failure,
  and profile cleanup more reliably.

## What was new in 0.7.0

- **Workspace scoping**: the viewer gallery now has a three-way scope —
  this session / this workspace (artifacts created from the same cwd) / all
  artifacts — and `list_artifacts` accepts an optional
  `scope: "session" | "workspace" | "all"` parameter.

## What was new in 0.6.0

- **Mermaid diagrams render live** in both stacks: markdown ` ```mermaid `
  fences and html `<pre class="mermaid">` blocks hydrate client-side under the
  strict CSP (theme follows light/dark; syntax errors show inline). The old
  `mermaid/not-validated` warning is gone.
- **Syntax highlighting** for fenced code blocks with a language tag
  (highlighted server-side via highlight.js; GitHub light/dark themes).
- **Footnotes** (`[^1]`) now render as a linked footnotes section.
- **Store cleanup**: new `delete_artifacts` bulk tool (by ids and/or age) and
  `/artifacts-clean <days>` command.
- Manifest writes are atomic (write-then-rename), hardening the shared store
  against crashes and concurrent sessions.

## Install

```bash
pi install npm:@jakeryderv/pi-artifacts
```

To try it for a single run without adding it to your Pi settings:

```bash
pi -e npm:@jakeryderv/pi-artifacts
```

## Quickstart

After installing or loading the package, ask Pi to create and render an artifact:

```text
Create a markdown artifact titled "Demo Report" with a heading, a short note callout, a task list, and a small table. Then render it.
```

Or an html dashboard with a chart:

```text
Create an html artifact titled "Q4 Dashboard" with a summary section and a bar chart of quarterly revenue. Then render it.
```

Pi will scaffold a bundle, write the entry file, validate it, and return
a localhost preview URL. Run `/viewer` to open the artifact gallery, then use
`list_artifacts` or `delete_artifact` when you want to inspect or clean up saved
bundles.

## What it provides

- **`scaffold_artifact`** tool — create an empty markdown or html artifact bundle to author into.
- **`render_artifact`** tool — validate/normalize an authored bundle and preview it on localhost.
  - **markdown:** Prettier + markdownlint + strict KaTeX math; GFM task lists, GitHub-style alerts, footnotes, syntax-highlighted code, and Mermaid fences rendered as live diagrams.
  - **html:** Prettier + HTMLHint + CSP/component capability checks; shared runtime (Pico CSS, declarative Web Components, artifact-local JSON feeds, Chart.js, Mermaid, and icons) injected from `/runtime`.
- **`export_artifact`** tool — write a self-contained HTML export to
  `<bundle>/exports/<id>.html`, with referenced assets and required runtime
  resources embedded.
- **`list_artifacts`** tool — list artifact bundles in the store, newest first;
  optionally scoped to the current session or workspace (cwd).
- **`delete_artifact`** tool — delete a bundle and all of its files from the store.
- **`delete_artifacts`** tool — bulk-delete bundles by id list and/or age.
- **`/artifacts-clean`** command — delete artifacts not updated in N days
  (`/artifacts-clean 30`); with no argument, shows the store size.
- **`/viewer`** command — open a live gallery of artifacts with a three-way
  scope (this session / this workspace / all artifacts), search/filter
  controls, render status badges, and auto-updating via Server-Sent Events as
  you render or delete. Gallery and shared-shell artifact pages include a
  persistent toolbar with navigation and a single-file Export action. Gallery
  rows also provide direct export downloads without writing an export file.
  Full authored HTML documents deliberately opt out of the shared shell, including
  its toolbar and live reload. When a Chromium-family
  browser is available it opens in a dedicated, chromeless app
  window (isolated profile, closed on session shutdown); otherwise it falls back
  to your default browser.
- **`/viewer-mode`** command — set how `/viewer` opens and remember it across
  sessions: `app` (dedicated window, default), `browser` (your default browser),
  or `off` (just print the URL — handy over SSH/headless). Run with no argument
  to see the current setting. One-off overrides: `PI_ARTIFACTS_VIEWER=app|browser|none`
  (env wins over the saved setting) and `PI_ARTIFACTS_BROWSER=<path>` (choose the
  app-mode browser binary).
- **`/viewer-auto`** command — toggle whether a successful render auto-shows the
  artifact: `on` (default) or `off`. When on, rendering opens the viewer if it
  isn't already; if a window is already open it switches to the freshly rendered
  artifact (no new window). Honors `/viewer-mode off` (stays quiet on
  SSH/headless). Run with no argument to see the current setting.
- **`artifacts-authoring`** skill — how to author portable markdown and html artifacts.

Artifacts are stored as content-only bundles under `~/.pi/artifacts/<id>/`
(`manifest.json` + entry file + `assets/`), keyed to their originating session
via provenance metadata in the manifest. Tool-generated standalone files live
under the bundle's `exports/` directory.

## Security

Pi packages run with full system access. This extension serves artifact previews
only from a localhost-bound server, scoped to the selected artifact directory,
with an unguessable per-server capability path and restrictive
Content-Security-Policy. html artifacts run under the same
strict CSP (`script-src 'self'`), but the package keeps artifacts content-only:
author-supplied inline JS, authored `<script src>` files, `on*=` handlers, and
`javascript:` URLs are blocked or rejected, and executable runtime JS is served
only from the package-owned `/runtime` namespace. Viewer, SSE, artifact pages,
and artifact assets require the random capability path; `/runtime` intentionally
remains a stable public path because it contains only immutable package-owned
assets, never artifact content. Review the source before installing.
Standalone exports embed a second restrictive CSP: referenced content assets are
converted to data URLs, package-owned runtime scripts receive a random nonce,
network connections are disabled, and authored executable hooks are removed.

## Development

```bash
# install dev + runtime dependencies
npm install

# checks
npm run typecheck
npm test
npm run lint:deps     # knip: unreachable files, unused exports, stray deps
npm run pack:check    # confirm the published tarball contents

# load the package for one isolated run from a scratch directory
cd "$(mktemp -d)"
pi -e /absolute/path/to/pi-artifacts
```

## License

MIT

@jakeryderv/pi-artifacts

Rich visualization artifacts for the Pi coding agent. Scaffold, validate, and preview artifact bundles — portable markdown documents and an interactive html stack (declarative components, Pico CSS, and CSP-clean Chart.js) — in a session-scoped viewer.

Status: markdown + declarative html, live viewer + single-file export. The package can scaffold markdown and html artifact bundles, validate/normalize them, serve localhost previews, and show a session-scoped browser gallery via /viewer that updates live (Server-Sent Events) as artifacts are rendered or deleted — and open artifact pages reload themselves when re-rendered. html artifacts get a shared runtime (Pico CSS, components, file-backed feeds, Chart.js, Mermaid, icons) injected under a strict CSP. See the roadmap, API contract, and design notes for the broader plan.

What's new in 0.9.1

Maintenance release — no artifact-authoring behavior changed.

Corrected package metadata. repository and homepage now point at github.com/jakeryderv/pi-artifacts; the 0.9.0 metadata still referenced the former monorepo path, so the links on npm resolved to a missing directory.
Releases are now published from CI on a v* tag using npm trusted publishing, so this and later versions carry a provenance attestation.

What's new in 0.9.0

Portable single-file HTML export for both markdown and html artifacts via export_artifact or the viewer's per-artifact Export action.
Package runtime CSS/JavaScript, KaTeX fonts, icons, referenced images, and artifact-local JSON feeds are embedded into the exported document.
Exports carry their own restrictive CSP, authorize only embedded package-owned runtime scripts, and remove authored executable scripts, event handlers, and javascript: URLs.

What's new in 0.8.1

Correct Markdown math boundaries: KaTeX rendering now operates on parsed Markdown text tokens, preserving dollar-delimited text inside inline and fenced code as code and avoiding ambiguous currency pairs.
Safer store operations: artifact IDs must be one generated slug segment, and concurrent manifest updates use independent atomic temporary files.
Dependency hardening: the minimum markdown-it version is raised to the patched 14.3 release line.

What's new in 0.8.0

Declarative HTML components: package-owned <pi-grid>, <pi-card>, <pi-metric>, <pi-chart>, and <pi-table> Web Components provide a consistent dashboard vocabulary without authored JavaScript or a build step.
Artifact-local data feeds: <pi-data-source> loads one-shot JSON snapshots from the bundle's assets/ directory and binds them to metrics, charts, and tables with data-feed and optional dotted field paths.
Viewer hardening: artifact content, gallery pages, and SSE now use a random per-server capability path; the preview server starts lazily and adds no-store and same-origin resource headers.
Cleaner internals and launcher lifecycle: renderer selection is centralized in a typed registry, while app mode tracks Chromium liveness, launch failure, and profile cleanup more reliably.

What was new in 0.7.0

Workspace scoping: the viewer gallery now has a three-way scope — this session / this workspace (artifacts created from the same cwd) / all artifacts — and list_artifacts accepts an optional scope: "session" | "workspace" | "all" parameter.

What was new in 0.6.0

Mermaid diagrams render live in both stacks: markdown ```mermaid fences and html <pre class="mermaid"> blocks hydrate client-side under the strict CSP (theme follows light/dark; syntax errors show inline). The old mermaid/not-validated warning is gone.
Syntax highlighting for fenced code blocks with a language tag (highlighted server-side via highlight.js; GitHub light/dark themes).
Footnotes ([^1]) now render as a linked footnotes section.
Store cleanup: new delete_artifacts bulk tool (by ids and/or age) and /artifacts-clean <days> command.
Manifest writes are atomic (write-then-rename), hardening the shared store against crashes and concurrent sessions.

Install

pi install npm:@jakeryderv/pi-artifacts

To try it for a single run without adding it to your Pi settings:

pi -e npm:@jakeryderv/pi-artifacts

Quickstart

After installing or loading the package, ask Pi to create and render an artifact:

Create a markdown artifact titled "Demo Report" with a heading, a short note callout, a task list, and a small table. Then render it.

Or an html dashboard with a chart:

Create an html artifact titled "Q4 Dashboard" with a summary section and a bar chart of quarterly revenue. Then render it.

Pi will scaffold a bundle, write the entry file, validate it, and return a localhost preview URL. Run /viewer to open the artifact gallery, then use list_artifacts or delete_artifact when you want to inspect or clean up saved bundles.

What it provides

scaffold_artifact tool — create an empty markdown or html artifact bundle to author into.
render_artifact tool — validate/normalize an authored bundle and preview it on localhost.
- markdown: Prettier + markdownlint + strict KaTeX math; GFM task lists, GitHub-style alerts, footnotes, syntax-highlighted code, and Mermaid fences rendered as live diagrams.
- html: Prettier + HTMLHint + CSP/component capability checks; shared runtime (Pico CSS, declarative Web Components, artifact-local JSON feeds, Chart.js, Mermaid, and icons) injected from /runtime.
export_artifact tool — write a self-contained HTML export to <bundle>/exports/<id>.html, with referenced assets and required runtime resources embedded.
list_artifacts tool — list artifact bundles in the store, newest first; optionally scoped to the current session or workspace (cwd).
delete_artifact tool — delete a bundle and all of its files from the store.
delete_artifacts tool — bulk-delete bundles by id list and/or age.
/artifacts-clean command — delete artifacts not updated in N days (/artifacts-clean 30); with no argument, shows the store size.
/viewer command — open a live gallery of artifacts with a three-way scope (this session / this workspace / all artifacts), search/filter controls, render status badges, and auto-updating via Server-Sent Events as you render or delete. Gallery and shared-shell artifact pages include a persistent toolbar with navigation and a single-file Export action. Gallery rows also provide direct export downloads without writing an export file. Full authored HTML documents deliberately opt out of the shared shell, including its toolbar and live reload. When a Chromium-family browser is available it opens in a dedicated, chromeless app window (isolated profile, closed on session shutdown); otherwise it falls back to your default browser.
/viewer-mode command — set how /viewer opens and remember it across sessions: app (dedicated window, default), browser (your default browser), or off (just print the URL — handy over SSH/headless). Run with no argument to see the current setting. One-off overrides: PI_ARTIFACTS_VIEWER=app|browser|none (env wins over the saved setting) and PI_ARTIFACTS_BROWSER=<path> (choose the app-mode browser binary).
/viewer-auto command — toggle whether a successful render auto-shows the artifact: on (default) or off. When on, rendering opens the viewer if it isn't already; if a window is already open it switches to the freshly rendered artifact (no new window). Honors /viewer-mode off (stays quiet on SSH/headless). Run with no argument to see the current setting.
artifacts-authoring skill — how to author portable markdown and html artifacts.

Artifacts are stored as content-only bundles under ~/.pi/artifacts/<id>/ (manifest.json + entry file + assets/), keyed to their originating session via provenance metadata in the manifest. Tool-generated standalone files live under the bundle's exports/ directory.

Security

Pi packages run with full system access. This extension serves artifact previews only from a localhost-bound server, scoped to the selected artifact directory, with an unguessable per-server capability path and restrictive Content-Security-Policy. html artifacts run under the same strict CSP (script-src 'self'), but the package keeps artifacts content-only: author-supplied inline JS, authored <script src> files, on*= handlers, and javascript: URLs are blocked or rejected, and executable runtime JS is served only from the package-owned /runtime namespace. Viewer, SSE, artifact pages, and artifact assets require the random capability path; /runtime intentionally remains a stable public path because it contains only immutable package-owned assets, never artifact content. Review the source before installing. Standalone exports embed a second restrictive CSP: referenced content assets are converted to data URLs, package-owned runtime scripts receive a random nonce, network connections are disabled, and authored executable hooks are removed.

Development

# install dev + runtime dependencies
npm install

# checks
npm run typecheck
npm test
npm run lint:deps     # knip: unreachable files, unused exports, stray deps
npm run pack:check    # confirm the published tarball contents

# load the package for one isolated run from a scratch directory
cd "$(mktemp -d)"
pi -e /absolute/path/to/pi-artifacts

License

MIT