diff --git a/CHANGELOG.md b/CHANGELOG.md index 75842c9..7505a57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,19 @@ All notable changes are documented here. +## Unreleased + +### Changed + +- `init` now ends by naming the one command that puts the map on screen + (`npx agent-runtime-map watch .`), in both languages and on both the plain and + `--github` paths. Every route out of `init` previously ended in a CI round trip + — commit, push, wait, download the artifact, serve it — so someone could finish + setup without ever seeing the map the tool exists to draw. +- The README (both languages) opens the usage section with that same one-command + run instead of the GitHub Action, and the header links to it. The Action stays + documented right below it as the way to keep the map current. + ## 0.9.1 - 2026-09-03 ### Fixed diff --git a/README.md b/README.md index 104b708..e1df089 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@

Open the live demo + · Map your own project · Install in a repository · npm

@@ -113,11 +114,24 @@ frames, edge-state tokens, and boundary measurement helpers for embedding the same map in another product. See [Visual Components](docs/VISUAL_COMPONENTS.md) for the component contract and integration example. +## Start here: your own map, one command + +Point it at a project and the interactive map opens in your browser. Nothing to +configure, no commit, no CI: + +```bash +npx agent-runtime-map@latest . +``` + +That is the whole first run. Add `watch` instead to keep the map live while you +edit, or `--no-open` to skip the browser. Once you have seen your own map, set up +the section below so it stays current without you asking. + ## Set it up once, GitHub keeps the map current -The primary way to use Agent Runtime Map: install it, run one init, commit the -workflow it generates — and from then on every push and pull request rebuilds the -map on GitHub automatically. +For continuous updates: install it, run one init, commit the workflow it +generates — and from then on every push and pull request rebuilds the map on +GitHub automatically. ```bash npm install --save-dev agent-runtime-map diff --git a/README.zh-CN.md b/README.zh-CN.md index 7725574..a1b1d0b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -12,7 +12,8 @@

打开在线 Demo - · 接入仓库 + · 一条命令看到自己的图 + · 接入仓库 · npm

@@ -80,10 +81,21 @@ Viewer 采用开源的工程蓝图视觉系统：细密网格画布、图标型 后台可以复用节点、分区边框、链路状态 token 和自动边界计算工具。组件接口和 嵌入示例见 [Visual Components](docs/VISUAL_COMPONENTS.md)。 -## 一次设置，GitHub 持续更新（主路径） +## 从这里开始：一条命令看到自己的图 -主用法：安装、执行一次 init、提交它生成的 workflow——之后每次 push 和 Pull -Request 都会在 GitHub 上自动重建地图。 +指向任意项目，交互式地图就在浏览器里打开。无需配置、无需提交、不用等 CI： + +```bash +npx agent-runtime-map@latest . +``` + +第一次就这一步。想让地图随代码改动一直刷新，把命令换成 `watch`；不想自动开 +浏览器，加 `--no-open`。看过自己的图之后，再按下一节配置持续更新。 + +## 一次设置，GitHub 持续更新 + +需要持续更新时：安装、执行一次 init、提交它生成的 workflow——之后每次 push 和 +Pull Request 都会在 GitHub 上自动重建地图。 ```bash npm install --save-dev agent-runtime-map diff --git a/packages/cli/src/continuous.ts b/packages/cli/src/continuous.ts index 87949dd..51657b0 100644 --- a/packages/cli/src/continuous.ts +++ b/packages/cli/src/continuous.ts @@ -39,7 +39,12 @@ export async function runInit( .map(([name, command]) => ` "${name}": "${command}"`) .join("\n"); process.stdout.write(`${text.initScripts(scripts)}\n`); - if (!options.github) return 0; + // The view hint goes last on both paths: it is the one instruction that ends with + // the map on screen, and `init --github` otherwise closes on a CI round trip. + if (!options.github) { + process.stdout.write(`${text.initViewHint}\n`); + return 0; + } try { const workflow = await initGithubWorkflow(projectPath, { force: options.force }); @@ -50,7 +55,7 @@ export async function runInit( : workflow.outcome === "overwritten" ? text.githubWorkflowOverwritten(workflow.workflowFile) : text.githubWorkflowUpdated(workflow.workflowFile); - process.stdout.write(`${line}\n${text.githubNextSteps}\n`); + process.stdout.write(`${line}\n${text.githubNextSteps}\n${text.initViewHint}\n`); return 0; } catch (error) { if (error instanceof WorkflowModifiedError) { diff --git a/packages/cli/src/i18n.ts b/packages/cli/src/i18n.ts index 12e06a5..8a01cd2 100644 --- a/packages/cli/src/i18n.ts +++ b/packages/cli/src/i18n.ts @@ -26,6 +26,7 @@ export interface CliText { initUnchanged(file: string): string; initScripts(scripts: string): string; initIgnored(rule: string, file: string): string; + initViewHint: string; configWarning(warning: string): string; buildUpdated(dir: string, buildId: string, ms: number): string; buildUnchanged(buildId: string): string; @@ -84,6 +85,11 @@ const TEXT: Record = { githubWorkflowUnchanged: (file) => `${file} is already current; nothing changed.`, githubWorkflowModified: (file) => `${file} exists and has local modifications, so it was NOT touched. Re-run with --force to overwrite it.`, githubNextSteps: `Next: commit agent-runtime-map.config.json and .github/workflows/agent-runtime-map.yml.\nEvery push, pull request, and a weekly schedule will then rebuild the map on GitHub:\nthe run's Summary shows what changed, and the full map (report.html) is attached as an artifact.`, + // Init is the moment someone has just installed and is still at the terminal. + // Without this line every documented path from here ends in CI: commit, push, + // wait, download an artifact, serve it — so a new user can finish setup having + // never once seen the map. The viewer is a single command away; say so here. + initViewHint: `To see the map right now, without committing or waiting for CI:\n npx agent-runtime-map watch .\nThat analyzes this project, opens the interactive viewer in your browser, and keeps\nboth current as you edit. Use \`build .\` for the files alone, without a viewer.`, forceRequiresGithub: "--force is only meaningful together with init --github", }, "zh-CN": { @@ -126,6 +132,7 @@ const TEXT: Record = { githubWorkflowUnchanged: (file) => `${file} 已是最新，未做修改。`, githubWorkflowModified: (file) => `${file} 已存在且包含你的手动修改，因此没有改动它。如需覆盖，请使用 --force 重新执行。`, githubNextSteps: `下一步：提交 agent-runtime-map.config.json 和 .github/workflows/agent-runtime-map.yml。\n之后每次 push、Pull Request 以及每周一次的定时任务都会在 GitHub 上自动重建地图：\n运行的 Summary 会显示变更摘要，完整地图（report.html）会作为 artifact 附在运行结果里。`, + initViewHint: `想立刻看到地图，无需提交、也不用等 CI：\n npx agent-runtime-map watch .\n该命令会分析当前项目，在浏览器中打开交互式界面，并随你改代码自动刷新。\n只要产物文件、不需要界面时，用 \`build .\`。`, forceRequiresGithub: "--force 只能与 init --github 一起使用", }, }; diff --git a/tests/i18n.test.ts b/tests/i18n.test.ts index 67e8e72..66d6c5f 100644 --- a/tests/i18n.test.ts +++ b/tests/i18n.test.ts @@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; import { analyzeTypeScriptProject } from "@agent-runtime-map/typescript"; import { compileLogicGraph } from "@agent-runtime-map/logic-compiler"; -import { helpText, localizedViewerUrl, resolveCliLocale } from "../packages/cli/src/i18n.js"; +import { cliText, helpText, localizedViewerUrl, resolveCliLocale } from "../packages/cli/src/i18n.js"; import { localizeDiagnostic, localizeFeatureLabel, @@ -25,6 +25,19 @@ describe("localization", () => { expect(localizedViewerUrl("http://127.0.0.1:4173", "zh-CN")).toBe("http://127.0.0.1:4173/?locale=zh-CN"); }); + it("tells a freshly initialized project how to open the viewer, in both languages", () => { + // Every other path out of init ends in CI — commit, push, wait, download an + // artifact, serve it — so without this line a user can finish setup having + // never seen the map. The command has to be runnable as printed. + for (const locale of ["en", "zh-CN"] as const) { + const hint = cliText(locale).initViewHint; + expect(hint).toContain("npx agent-runtime-map watch ."); + // A hint that does not promise a viewer does not fix the problem it exists for. + expect(hint).toMatch(locale === "en" ? /viewer/i : /界面/); + } + expect(cliText("zh-CN").initViewHint).not.toBe(cliText("en").initViewHint); + }); + it("localizes generated graph semantics while preserving code-backed metadata", async () => { const raw = await analyzeTypeScriptProject(fixture); const graph = compileLogicGraph(raw, { maxNodes: 40 });