Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
feat: open verified deliveries (#39)
tt-a1i4153caea4451
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex e10e7ba2..20ce346f 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -87,6 +87,10 @@ jobs:node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.htmlnode bin/archify.mjs check /tmp/workflow.htmlnode bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow-delivered.html --quality showcase --json+ node_path="$(command -v node)"+ mkdir -p /tmp/archify-empty-path+ PATH=/tmp/archify-empty-path "$node_path" bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow-open-fallback.html --open --json > /tmp/workflow-open-receipt.json+ node -e "const r=require('/tmp/workflow-open-receipt.json'); if (!r.ok || r.open?.status !== 'unsupported') process.exit(1)"node bin/archify.mjs validate architecture examples/web-app.architecture.json --jsonnode bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --jsondiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8e493e1c..f0d6471c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,8 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo## [Unreleased]### Added+- **Verified Open.** `archify deliver ... --open` now hands the exact committed absolute HTML path to the native macOS, Linux, or Windows opener only after render, artifact checks, receipt creation, and atomic replacement succeed. The option is off by default, uses bounded argument arrays without shell interpolation, and never runs on a failed delivery. Missing, unsupported, timed-out, or failed openers leave the verified artifact successful, add a truthful `open.status` to the one-object JSON receipt, and print the manual absolute path to stderr. No viewer, server, watcher, dependency, network, storage, schema, renderer, layout, export, or mobile surface was added.+- **Share Card export.** Every ordinary artifact can now export one canonical 1200×630 PNG for README, release, social, and launch previews. The fixed card chrome fits title and subtitle while the full diagram uses contain-only placement without cropping, preserves the current theme and visual preset, and reuses canonical cleanup so temporary viewer state never enters the image. Exact dimensions, bytes, filename, and canonical state are recorded without claiming validation. Wide-architecture and tall-sequence pixel smoke tests reject blank or malformed cards.- **Atomic Verified Delivery.** The zero-dependency CLI now exposes `archify deliver <type> <input.json> [output.html]`: it renders into a unique candidate beside the target, runs the existing eight artifact and composition checks, computes an exact byte count and SHA-256 receipt, and atomically replaces the target only after every deterministic gate passes. `--json` returns stable success or input/prepare/render/check/receipt/commit failure facts for agents and CI. Any failure removes the candidate and preserves the previous artifact byte-for-byte. Existing `render`, `validate`, and `check` behavior remains available for iteration and diagnosis; no schema, renderer, layout, viewer, dependency, network, storage, export, or mobile surface changed. The ZIP builder now also resolves caller-relative output paths before entering its temporary staging directory, and CI exercises that exact packaged path.- **Live Visual Style Try-on.** Every generated artifact now exposes one compact `Style` control and <kbd>S</kbd> shortcut that cycles the existing Classic, Signal Flow, and Blueprint presets over the exact same authored topology. The page and canonical SVG update together, so an explicit reader choice reaches PNG/JPEG/WebP/SVG/WebM export without moving a node or relationship. The authored preset remains the reload default; no preference, URL, source JSON, schema, layout, dependency, fourth style, or dedicated mobile surface is added, and passive embeds/print remain control-free. A same-topology regression proves canonical SVG geometry is identical across all three presets.- **Ambiguous Relationship Corridor Gate.** Unrelated relationships that overlap along the same orthogonal lane for at least 8px now produce exact `composition/ambiguous-corridor` evidence instead of silently reading as a false merge or branch. `standard` keeps dense engineering diagrams renderable and records the finding as a warning; `showcase` rejects it before write and in the final artifact check. Relationships sharing a semantic endpoint, point touches, and shorter overlaps remain legal. Two canonical outer-rail routes were repaired without heuristic rerouting, all five renderers share the same detector, and Proof Lab grows to 88/88 checks with zero corridor debt.diff --git a/README.md b/README.mdindex 60f1afdf..b769eded 100644--- a/README.md+++ b/README.md@@ -21,7 +21,7 @@ Archify is an agent skill for Claude, Codex CLI, and opencode. It produces a sel- **Portable exports** — create a 1200×630 Share Card, copy PNG, or download PNG, JPEG, WebP, dual-theme SVG, and trace-enabled WebM- **Typed and checked** — JSON IR, bundled schema validation, default semantic safety gates, and opt-in composition profiles- **Self-contained output** — one shareable HTML file with no viewer runtime dependency-- **Built for agent workflows** — install once, then create and refine diagrams through conversation+- **Built for agent workflows** — install once, then create and refine diagrams through conversation; optionally open only the verified final artifact@@ -152,7 +152,7 @@ Archify is not a general-purpose drawing editor or a Mermaid theme. It turns tec|---|---|| **Generate** | The agent creates typed JSON IR from your description. || **Validate** | Bundled validators and layout rules check the source. |-| **Deliver** | A same-directory candidate is rendered and checked; only a passing artifact atomically replaces the target. |+| **Deliver** | A same-directory candidate is rendered and checked; only a passing artifact atomically replaces the target, then optional `--open` launches that exact file. || **Iterate** | The agent updates the source while unrelated structure stays stable. |Useful repository commands:@@ -163,9 +163,11 @@ node bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demonode bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json-node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --json+node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json```+Use `--open` for an interactive local handoff. It is off by default, runs only after the verified artifact is committed, and never turns a successful delivery into a failure when the OS opener is unavailable; JSON stays on stdout and the absolute manual-open path goes to stderr.+Optional motion and presentation styling are explicit:```jsondiff --git a/README_EN.md b/README_EN.mdindex 60f1afdf..b769eded 100644--- a/README_EN.md+++ b/README_EN.md@@ -21,7 +21,7 @@ Archify is an agent skill for Claude, Codex CLI, and opencode. It produces a sel- **Portable exports** — create a 1200×630 Share Card, copy PNG, or download PNG, JPEG, WebP, dual-theme SVG, and trace-enabled WebM- **Typed and checked** — JSON IR, bundled schema validation, default semantic safety gates, and opt-in composition profiles- **Self-contained output** — one shareable HTML file with no viewer runtime dependency-- **Built for agent workflows** — install once, then create and refine diagrams through conversation+- **Built for agent workflows** — install once, then create and refine diagrams through conversation; optionally open only the verified final artifact@@ -152,7 +152,7 @@ Archify is not a general-purpose drawing editor or a Mermaid theme. It turns tec|---|---|| **Generate** | The agent creates typed JSON IR from your description. || **Validate** | Bundled validators and layout rules check the source. |-| **Deliver** | A same-directory candidate is rendered and checked; only a passing artifact atomically replaces the target. |+| **Deliver** | A same-directory candidate is rendered and checked; only a passing artifact atomically replaces the target, then optional `--open` launches that exact file. || **Iterate** | The agent updates the source while unrelated structure stays stable. |Useful repository commands:@@ -163,9 +163,11 @@ node bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demonode bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json-node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --json+node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json```+Use `--open` for an interactive local handoff. It is off by default, runs only after the verified artifact is committed, and never turns a successful delivery into a failure when the OS opener is unavailable; JSON stays on stdout and the absolute manual-open path goes to stderr.+Optional motion and presentation styling are explicit:```jsondiff --git a/README_ZH.md b/README_ZH.mdindex bbc4efcf..677cf242 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -17,7 +17,7 @@ Archify 是一个可用于 Claude、Codex CLI 和 opencode 的 Agent Skill。它- **便携导出** —— 一键生成 1200×630 Share Card,复制 PNG,或下载 PNG / JPEG / WebP / 双主题 SVG / WebM- **Typed + Checked** —— Typed JSON IR、内置 Schema 校验、默认语义安全门禁和可选构图档位- **结果完全独立** —— 一个 HTML 文件即可查看和分享,不依赖 Viewer 服务-- **适合 Agent 工作流** —— 安装一次,通过对话持续生成和细调+- **适合 Agent 工作流** —— 安装一次,通过对话持续生成和细调;需要时只打开已经验证的最终成品@@ -148,7 +148,7 @@ Archify 不是通用绘图编辑器,也不是 Mermaid 主题;它负责把技|---|---|| **生成** | Agent 根据描述创建 Typed JSON IR。 || **校验** | 内置 Validator 和布局规则检查源文件。 |-| **交付** | 在目标同目录生成并检查候选;只有通过门禁的结果才原子替换目标文件。 |+| **交付** | 在目标同目录生成并检查候选;只有通过门禁的结果才原子替换目标文件,随后可选用 `--open` 打开这个确切成品。 || **迭代** | Agent 修改源文件,不干扰无关结构。 |仓库常用命令:@@ -159,9 +159,11 @@ node bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demonode bin/archify.mjs guide "展示 CI/CD 检查、审批、部署和回滚"node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json-node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --json+node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json```+`--open` 只适合本地交互式交付。它默认关闭,并且只在验证成品原子提交后执行;系统无法打开时,交付仍保持成功,JSON 只写 stdout,stderr 会给出可手动打开的绝对路径。+动态和演示样式需要显式选择:```jsondiff --git a/ROADMAP.md b/ROADMAP.mdindex 25f710f4..c1814a1c 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -1,8 +1,12 @@# Archify Roadmap-As of v2.11.0, the coordinate-stability work has shipped as JSON IR plus typed renderers for architecture, workflow, sequence, data-flow, and lifecycle diagrams. Workflow diagrams now also have phase/group/exception-lane structure, happy-path linting, trace animation, and route-crossing guards. The shared viewer adds deterministic semantic node IDs, optional author-controlled relationship IDs with durable `#relation=` links, a pre-click Intent Trace for exact one-hop traffic, a two-endpoint Route Probe with an inspectable Route Journey over deterministic shortest authored paths, searchable Node Finder navigation, read-only one-hop focus with a renderer-owned Semantic Passport and copyable focus link, a runtime-built Semantic Radar for desktop viewport navigation, bounded typed guided views with a visible Named Chapter Rail, pre-commit Chapter Delta Preview, Shared Anchor Handoff, and path-aware Semantic Story Beats, a reader-controlled Live/Still Motion Governor, share-ready one-shot chapters with a title/route/step/state/progress cue, a viewport-filling Presentation Stage, Semantic Camera framing, pan/zoom, three reader-switchable visual presets, and browser-native WebM export. A generated Proof Lab publishes 11 live scenario artifacts with their exact sources, three named reader views, 88 artifact checks, and named composition receipts; its preview grid stays static while deliberate proof links play one named chapter once. The landing-page Live Proof Stage promotes three of those generated artifacts into the first bounded motion proof, and the README motion reel carries the same proof-first story onto GitHub without claiming SVG animation support. A question-first scenario guide maps concrete user needs to those 11 bounded recipes across the five modes, with one shared source for CLI and GitHub Pages and direct proof navigation. A unified CLI (`bin/archify.mjs`) wraps guide, render, deliver, validate, check, and examples. This file records the design decisions that led there, plus the ideas that were explicitly declined. The original v2.4 / v2.5 backlog (export-scale URL param, color-blind palette, gzip+base64 share links) was considered and dropped — see [Not planned](#not-planned) for the rationale on each.+As of v2.11.0, the coordinate-stability work has shipped as JSON IR plus typed renderers for architecture, workflow, sequence, data-flow, and lifecycle diagrams. Workflow diagrams now also have phase/group/exception-lane structure, happy-path linting, trace animation, and route-crossing guards. The shared viewer adds deterministic semantic node IDs, optional author-controlled relationship IDs with durable `#relation=` links, a pre-click Intent Trace for exact one-hop traffic, a two-endpoint Route Probe with an inspectable Route Journey over deterministic shortest authored paths, searchable Node Finder navigation, read-only one-hop focus with a renderer-owned Semantic Passport and copyable focus link, a runtime-built Semantic Radar for desktop viewport navigation, bounded typed guided views with a visible Named Chapter Rail, pre-commit Chapter Delta Preview, Shared Anchor Handoff, and path-aware Semantic Story Beats, a reader-controlled Live/Still Motion Governor, share-ready one-shot chapters with a title/route/step/state/progress cue, a viewport-filling Presentation Stage, Semantic Camera framing, pan/zoom, three reader-switchable visual presets, a contain-only 1200×630 Share Card, and browser-native WebM export. A generated Proof Lab publishes 11 live scenario artifacts with their exact sources, three named reader views, 88 artifact checks, and named composition receipts; its preview grid stays static while deliberate proof links play one named chapter once. The landing-page Live Proof Stage promotes three of those generated artifacts into the first bounded motion proof, and the README motion reel carries the same proof-first story onto GitHub without claiming SVG animation support. A question-first scenario guide maps concrete user needs to those 11 bounded recipes across the five modes, with one shared source for CLI and GitHub Pages and direct proof navigation. A unified CLI (`bin/archify.mjs`) wraps guide, render, deliver, validate, check, and examples, with an optional verified post-commit open for interactive local handoff. This file records the design decisions that led there, plus the ideas that were explicitly declined. The original v2.4 / v2.5 backlog (export-scale URL param, color-blind palette, gzip+base64 share links) was considered and dropped — see [Not planned](#not-planned) for the rationale on each.-The latest stability slice adds Atomic Verified Delivery. `archify deliver` writes the selected renderer into a unique same-directory candidate, applies all existing artifact and composition checks, builds an exact byte/SHA-256 receipt, and uses one rename as the only commit point. Input, prepare, render, check, receipt, and commit failures return named machine-readable stages, remove the candidate, and preserve any previous artifact byte-for-byte. Installed skills without `node_modules` retain the same contract across all five modes. Existing iteration commands remain compatible, while schema, renderer geometry, viewer behavior, dependencies, network, storage, exports, and mobile scope remain unchanged.+The latest onboarding slice adds Verified Open. `archify deliver ... --open` invokes only the exact absolute final HTML after every renderer, checker, receipt, and atomic-commit gate has passed. macOS, Linux, and Windows use bounded argument-array openers with no shell interpolation. Unsupported, missing, timed-out, or failed openers leave the verified delivery successful, preserve one-object JSON stdout, record a truthful `open.status`, and print the manual absolute path to stderr. The option is off by default and adds no viewer mutation, server, watch process, dependency, network, storage, schema, renderer, layout, export, or mobile surface.++The previous export slice added a canonical 1200×630 Share Card PNG for README, release, social, and launch previews. It contains the complete diagram without crop, uses the reader's current theme and visual preset, fits title and subtitle into fixed card chrome, and removes all temporary viewer state through the existing canonical serializer. Exact dimensions, bytes, and canonical state are recorded in the export receipt; the image makes no validation claim. Real wide-architecture and tall-sequence pixel gates reject blank or malformed cards without adding a server, dependency, schema, layout, storage, or dedicated mobile surface.++The previous stability slice added Atomic Verified Delivery. `archify deliver` writes the selected renderer into a unique same-directory candidate, applies all existing artifact and composition checks, builds an exact byte/SHA-256 receipt, and uses one rename as the only commit point. Input, prepare, render, check, receipt, and commit failures return named machine-readable stages, remove the candidate, and preserve any previous artifact byte-for-byte. Installed skills without `node_modules` retain the same contract across all five modes. Existing iteration commands remain compatible, while schema, renderer geometry, viewer behavior, dependencies, network, storage, exports, and mobile scope remain unchanged.The previous visual slice added Live Visual Style Try-on. Every ordinary generated artifact can cycle Classic, Signal Flow, and Blueprint with one compact toolbar control or <kbd>S</kbd>; the document root and canonical SVG change in lockstep, so the reader can export the deliberately selected treatment while node and relationship geometry stays byte-identical. The authored preset remains the reload default, and embed/print remain control-free. No preference storage, URL state, source mutation, schema, layout algorithm, dependency, fourth style, or dedicated mobile surface was added. A same-topology cross-preset regression turns the useful Fireworks style-matrix idea into a stability gate rather than a catalogue-expansion excuse.diff --git a/archify.zip b/archify.zipindex 98fd8bd1..3904d339 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex c6dd4cee..0f9c52f4 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -1,6 +1,6 @@---name: archify-description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, semantic navigation, optional trace motion, an optional 1200×630 Share Card PNG, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, approval or CI/CD flows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid. Prefer typed JSON IR renderers and deterministic validation; deliver static output by default and enable motion only when requested.+description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, semantic navigation, optional trace motion, an optional 1200×630 Share Card PNG, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, approval or CI/CD flows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid. Prefer typed JSON IR renderers and deterministic validation; deliver static output by default, enable motion only when requested, and use optional post-commit opening only for an interactive local handoff.license: MITmetadata:version: "2.11"@@ -77,7 +77,7 @@ All five modes follow the same loop:1. **Read first**: the schema (`schemas/<type>.schema.json`) and the complete worked example (`examples/*.{architecture,workflow,sequence,dataflow,lifecycle}.json`) — copy its patterns instead of guessing field shapes.2. Write `<name>.<type>.json`.3. Preflight while iterating: `node bin/archify.mjs validate <type> <input>.json --json`, explicitly adding `--quality standard` for dense engineering diagrams or `--quality showcase` for polished delivery. Use `render` plus `check` separately only when diagnosing a candidate.-4. Commit the final artifact with `node bin/archify.mjs deliver <type> <input>.json <output>.html --json` and the chosen `--quality`. Deliver renders a unique same-directory candidate, runs the complete artifact checker, computes the exact byte count and SHA-256 receipt, and only replaces the target after all artifact checks pass. Renderer, checker, receipt, or commit failure returns non-zero, removes the candidate, and preserves the previous target unchanged.+4. Commit the final artifact with `node bin/archify.mjs deliver <type> <input>.json <output>.html --json` and the chosen `--quality`. Deliver renders a unique same-directory candidate, runs the complete artifact checker, computes the exact byte count and SHA-256 receipt, and only replaces the target after all artifact checks pass. Add `--open` only when the user wants an immediate local preview: it runs after that atomic commit, uses one argument-array OS opener with a five-second bound, and records `open.status` without changing delivery success when opening fails or is unsupported. Keep it off for CI, unattended agents, and non-interactive environments. Renderer, checker, receipt, or commit failure returns non-zero, removes the candidate, preserves the previous target unchanged, and never invokes an opener.5. If any step fails, the error names the JSON path or the fix (thresholds, valid ranges, which knob to change). Fix the JSON and re-run; never edit the renderer.Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. The renderers additionally fail fast on established layout problems: node/state overlap (including cross-lane), labels colliding with nodes or other labels, labels wider than their node, out-of-range columns/rows, too-short edges, and legends outside the viewBox. A relationship passing through an unrelated opaque semantic node is always a hard correctness failure, even when neither `meta.quality_profile` nor CLI `--quality` is present: paint order must never make one authored relationship look like a different topology. The shared Clean Flow Gate reports `clean-flow/edge-through-node`, the exact collection/index and optional relationship ID, obstacle ID, first intersecting segment, 2px clearance, and supported routing/placement knobs before output is written. Stricter composition preferences remain profile-aware. For new or edited work, choose `standard` or `showcase` explicitly; structural container-border rules apply to both explicit profiles, unrelated proper X crossings and unrelated collinear overlaps of at least 8px warn in `standard` and fail in `showcase`, and showcase also fails any sub-8px route segment and sub-16px interior turn while preserving ordinary 8–15px endpoint stubs. Collinear corridors are not proper crossings; the separate `composition/ambiguous-corridor` rule exempts relationships with a shared semantic endpoint, point touches, and overlaps below 8px. Source/target boxes are endpoints; boundaries, lanes, stages, lifecycle bands, sequence segments/lifelines/activations, and other containers remain intentional pass-through geometry. CJK text is measured at double width automatically.@@ -348,7 +348,7 @@ Typography inherits JetBrains Mono from the SVG root. Sizes: 11–12px componentTreat the first render as a candidate, not an automatic final result. After deterministic render, validate, and artifact checks pass, inspect the final browser artifact and a canonical raster export when an image reader is available. Check clipping, text fit, hierarchy, whitespace, misleading routes, label placement, and dark/light readability. Make a maximum of two focused correction rounds; change only the diagnosed coordinates, labels, routes, spacing, or viewBox, then rerun render, validate, and check after every round.-Use `deliver` for every final replacement, including after a visual correction. Its JSON receipt proves only deterministic renderer and artifact-check facts; never claim that the deterministic receipt includes visual review. Perceptual review remains the separate truthful receipt below.+Use `deliver` for every final replacement, including after a visual correction. Its JSON receipt proves only deterministic renderer and artifact-check facts; never claim that the deterministic receipt includes visual review. `--open` is only a post-commit convenience and its status proves only whether the local opener invocation succeeded. Perceptual review remains the separate truthful receipt below.Finish with a truthful receipt:diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex 6ee841a4..2fdda04b 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -15,7 +15,7 @@ const TYPES = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifefunction usage() {return `Usage:archify render <type> <input.json> [output.html] [--quality standard|showcase]- archify deliver <type> <input.json> [output.html] [--json] [--quality standard|showcase]+ archify deliver <type> <input.json> [output.html] [--json] [--open] [--quality standard|showcase]archify validate <type> <input.json> [--json] [--layout-json] [--quality standard|showcase]archify inspect <type> <input.json>archify check <output.html>@@ -104,12 +104,14 @@ function reportDeliveryFailure({ json, stage, type, input, output, error, statusprocess.exitCode = status;}-function commandDeliver(args) {+async function commandDeliver(args) {const qualityArgs = extractQualityArgs(args);const json = qualityArgs.rest.includes('--json');- const unknown = qualityArgs.rest.filter((arg) => arg.startsWith('--') && arg !== '--json');+ const open = qualityArgs.rest.includes('--open');+ const knownOptions = new Set(['--json', '--open']);+ const unknown = qualityArgs.rest.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));if (unknown.length) fail(`Unknown deliver option "${unknown[0]}".`);- const positional = qualityArgs.rest.filter((arg) => arg !== '--json');+ const positional = qualityArgs.rest.filter((arg) => !knownOptions.has(arg));const [type, input, requestedOutput] = positional;if (!type || !input || positional.length > 3) fail(usage());@@ -276,11 +278,29 @@ function commandDeliver(args) {return;}+ if (open) {+ try {+ const { openArtifact } = await import('./open-artifact.mjs');+ receipt.open = openArtifact(outputPath);+ } catch {+ receipt.open = {+ requested: true,+ status: 'unsupported',+ target: outputPath,+ method: null,+ };+ }+ if (receipt.open.status !== 'opened') {+ console.error(`Could not open the verified artifact (${receipt.open.status}). Open it manually: ${outputPath}`);+ }+ }+if (json) {console.log(JSON.stringify(receipt, null, 2));} else {console.log(`delivered ${type} ${outputPath}`);console.log(`${receipt.validation.checksPassed}/${receipt.validation.checkCount} artifact checks; composition ${receipt.validation.compositionProfile}: ${receipt.validation.compositionStatus}; sha256 ${receipt.artifact.sha256.slice(0, 12)}`);+ if (receipt.open?.status === 'opened') console.log(`opened ${outputPath}`);}} finally {try {@@ -552,7 +572,7 @@ switch (command) {commandRender(args);break;case 'deliver':- commandDeliver(args);+ await commandDeliver(args);break;case 'validate':commandValidate(args);diff --git a/archify/bin/open-artifact.mjs b/archify/bin/open-artifact.mjsnew file mode 100644index 00000000..d7f066a5--- /dev/null+++ b/archify/bin/open-artifact.mjs@@ -0,0 +1,67 @@+import { spawnSync } from 'node:child_process';+import path from 'node:path';++const OPENERS = {+ darwin: {+ command: 'open',+ method: 'open',+ args: (target) => [target],+ },+ linux: {+ command: 'xdg-open',+ method: 'xdg-open',+ args: (target) => [target],+ },+ win32: {+ command: 'powershell.exe',+ method: 'powershell',+ // Keep the command constant and pass the target through PowerShell's+ // argument array. Paths are never interpolated into executable source.+ args: (target) => [+ '-NoProfile',+ '-NonInteractive',+ '-Command',+ 'Start-Process -FilePath $args[0]',+ target,+ ],+ },+};++export function openArtifact(target, options = {}) {+ const absoluteTarget = path.resolve(target);+ const platform = options.platform || process.platform;+ const opener = OPENERS[platform];+ if (!opener) {+ return {+ requested: true,+ status: 'unsupported',+ target: absoluteTarget,+ method: null,+ };+ }++ const spawn = options.spawn || spawnSync;+ let result;+ try {+ result = spawn(opener.command, opener.args(absoluteTarget), {+ encoding: 'utf8',+ shell: false,+ stdio: 'ignore',+ timeout: options.timeoutMs || 5000,+ windowsHide: true,+ });+ } catch {+ result = { error: new Error('opener threw') };+ }++ let status = 'opened';+ if (result?.error?.code === 'ENOENT') status = 'unsupported';+ else if (result?.error || result?.signal || result?.status !== 0) status = 'failed';++ return {+ requested: true,+ status,+ target: absoluteTarget,+ method: opener.method,+ };+}diff --git a/archify/test/cli.test.mjs b/archify/test/cli.test.mjsindex b9a52892..08d8da66 100644--- a/archify/test/cli.test.mjs+++ b/archify/test/cli.test.mjs@@ -24,6 +24,35 @@ function sha256(file) {return createHash('sha256').update(fs.readFileSync(file)).digest('hex');}+function makeFakeOpeners(name, { exitCode = 0 } = {}) {+ const bin = path.join(tmp, name);+ const log = path.join(bin, 'open-log.json');+ fs.mkdirSync(bin, { recursive: true });+ const source = `#!/usr/bin/env node+import fs from 'node:fs';+const target = process.argv.at(-1);+fs.writeFileSync(process.env.ARCHIFY_TEST_OPEN_LOG, JSON.stringify({+ argv: process.argv.slice(2),+ target,+ existed: fs.existsSync(target),+}));+process.exit(${exitCode});+`;+ for (const command of ['open', 'xdg-open']) {+ const executable = path.join(bin, command);+ fs.writeFileSync(executable, source);+ fs.chmodSync(executable, 0o755);+ }+ return {+ log,+ env: {+ ...process.env,+ PATH: `${bin}${path.delimiter}${process.env.PATH || ''}`,+ ARCHIFY_TEST_OPEN_LOG: log,+ },+ };+}+function copyInstalledSkill(target) {fs.cpSync(skillRoot, target, {recursive: true,@@ -44,6 +73,7 @@ test('cli: help lists commands and diagram types', () => {assert.equal(result.status, 0, result.stderr);assert.match(result.stdout, /archify render <type>/);assert.match(result.stdout, /archify deliver <type>/);+ assert.match(result.stdout, /--open/);assert.match(result.stdout, /archify guide \[scenario or question\]/);assert.match(result.stdout, /archify doctor/);assert.match(result.stdout, /archify demo \[output-directory\]/);@@ -221,6 +251,90 @@ test('cli: deliver atomically writes a checked artifact and structured receipt',errors: 0,warnings: 0,});+ assert.equal('open' in receipt, false);+});++test('cli: deliver --open launches only the committed absolute artifact as one argument', {+ skip: process.platform === 'win32',+}, () => {+ const fake = makeFakeOpeners('successful-open');+ const out = path.join(tmp, `-复杂 path 'quoted'`, 'verified diagram.html');+ const input = path.join(skillRoot, 'examples/agent-tool-call.workflow.json');+ const result = run(['deliver', 'workflow', input, out, '--open', '--json'], { env: fake.env });++ assert.equal(result.status, 0, result.stderr);+ const receipt = JSON.parse(result.stdout);+ assert.deepEqual(receipt.open, {+ requested: true,+ status: 'opened',+ target: out,+ method: process.platform === 'darwin' ? 'open' : 'xdg-open',+ });+ const invocation = JSON.parse(fs.readFileSync(fake.log, 'utf8'));+ assert.equal(invocation.existed, true, 'the opener must run after the atomic commit');+ assert.deepEqual(invocation.argv, [out]);+ assert.equal(invocation.target, out);+ assert.equal(fs.existsSync(out), true);+});++test('cli: opener failure does not invalidate a verified delivery or pollute json stdout', {+ skip: process.platform === 'win32',+}, () => {+ const fake = makeFakeOpeners('failed-open', { exitCode: 17 });+ const out = path.join(tmp, 'open-failure-preserves-delivery.html');+ const input = path.join(skillRoot, 'examples/web-app.architecture.json');+ const result = run(['deliver', 'architecture', input, out, '--open', '--json'], { env: fake.env });++ assert.equal(result.status, 0, result.stderr);+ const receipt = JSON.parse(result.stdout);+ assert.equal(receipt.ok, true);+ assert.equal(receipt.open.status, 'failed');+ assert.equal(receipt.open.target, out);+ assert.match(result.stderr, /Could not open the verified artifact/);+ assert.match(result.stderr, new RegExp(out.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));+ assert.equal(fs.existsSync(out), true);+ assert.equal(receipt.artifact.sha256, sha256(out));+});++test('cli: deliver failure never invokes the optional opener', {+ skip: process.platform === 'win32',+}, () => {+ const fake = makeFakeOpeners('never-open');+ const input = path.join(tmp, 'invalid-open-delivery.json');+ fs.writeFileSync(input, '{broken json');+ const out = path.join(tmp, 'must-not-open.html');+ const result = run(['deliver', 'architecture', input, out, '--open', '--json'], { env: fake.env });++ assert.equal(result.status, 1);+ assert.equal(JSON.parse(result.stdout).stage, 'input');+ assert.equal(fs.existsSync(fake.log), false);+ assert.equal(fs.existsSync(out), false);+});++test('cli: a missing optional opener module preserves verified delivery with a fallback receipt', () => {+ const installedRoot = path.join(tmp, 'missing-open-module-skill');+ copyInstalledSkill(installedRoot);+ const installedCli = path.join(installedRoot, 'bin/archify.mjs');+ fs.rmSync(path.join(installedRoot, 'bin/open-artifact.mjs'));+ const input = path.join(installedRoot, 'examples/agent-tool-call.workflow.json');+ const out = path.join(tmp, 'missing-open-module-delivery.html');++ const result = spawnSync(process.execPath, [installedCli, 'deliver', 'workflow', input, out, '--open', '--json'], {+ cwd: installedRoot,+ encoding: 'utf8',+ });++ assert.equal(result.status, 0, result.stderr);+ const receipt = JSON.parse(result.stdout);+ assert.equal(receipt.ok, true);+ assert.deepEqual(receipt.open, {+ requested: true,+ status: 'unsupported',+ target: out,+ method: null,+ });+ assert.match(result.stderr, /Open it manually/);+ assert.equal(receipt.artifact.sha256, sha256(out));});test('cli: deliver preserves the renderer default output contract', () => {diff --git a/archify/test/delivery-contract.test.mjs b/archify/test/delivery-contract.test.mjsindex 6eaa0c07..9f3af744 100644--- a/archify/test/delivery-contract.test.mjs+++ b/archify/test/delivery-contract.test.mjs@@ -21,3 +21,11 @@ test('skill uses atomic verified delivery for the final artifact', () => {assert.match(skill, /only replaces the target after.*artifact checks pass/i);assert.match(skill, /never claim that the deterministic receipt includes visual review/i);});++test('skill keeps optional opening behind the verified commit and outside automation', () => {+ assert.match(skill, /Add `--open` only when the user wants an immediate local preview/);+ assert.match(skill, /runs after that atomic commit/);+ assert.match(skill, /Keep it off for CI, unattended agents, and non-interactive environments/);+ assert.match(skill, /never invokes an opener/);+ assert.match(skill, /status proves only whether the local opener invocation succeeded/);+});diff --git a/archify/test/open-artifact.test.mjs b/archify/test/open-artifact.test.mjsnew file mode 100644index 00000000..c2c4e4ff--- /dev/null+++ b/archify/test/open-artifact.test.mjs@@ -0,0 +1,86 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import path from 'node:path';++import { openArtifact } from '../bin/open-artifact.mjs';++const target = path.resolve("/tmp/-复杂 path 'quoted'/diagram.html");++test('open artifact: uses argument arrays without shell interpolation on every supported platform', () => {+ const cases = [+ {+ platform: 'darwin',+ command: 'open',+ args: [target],+ method: 'open',+ },+ {+ platform: 'linux',+ command: 'xdg-open',+ args: [target],+ method: 'xdg-open',+ },+ {+ platform: 'win32',+ command: 'powershell.exe',+ args: [+ '-NoProfile',+ '-NonInteractive',+ '-Command',+ 'Start-Process -FilePath $args[0]',+ target,+ ],+ method: 'powershell',+ },+ ];++ for (const expected of cases) {+ let invocation;+ const result = openArtifact(target, {+ platform: expected.platform,+ spawn(command, args, options) {+ invocation = { command, args, options };+ return { status: 0 };+ },+ });++ assert.deepEqual(result, {+ requested: true,+ status: 'opened',+ target,+ method: expected.method,+ });+ assert.equal(invocation.command, expected.command);+ assert.deepEqual(invocation.args, expected.args);+ assert.equal(invocation.options.shell, false);+ assert.equal(invocation.options.timeout, 5000);+ }+});++test('open artifact: distinguishes missing support from opener execution failure', () => {+ const missing = openArtifact(target, {+ platform: 'linux',+ spawn() {+ return { error: Object.assign(new Error('missing'), { code: 'ENOENT' }) };+ },+ });+ assert.equal(missing.status, 'unsupported');+ assert.equal(missing.method, 'xdg-open');++ const timedOut = openArtifact(target, {+ platform: 'darwin',+ spawn() {+ return { error: Object.assign(new Error('timed out'), { code: 'ETIMEDOUT' }) };+ },+ });+ assert.equal(timedOut.status, 'failed');+ assert.equal(timedOut.method, 'open');++ const unknown = openArtifact(target, { platform: 'plan9' });+ assert.deepEqual(unknown, {+ requested: true,+ status: 'unsupported',+ target,+ method: null,+ });+});